### Full Workflow Example

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/MANIFEST.md

Provides a comprehensive example of how to integrate the Context7Action class into a GitHub Actions workflow, showcasing a complete lifecycle from setup to execution.

```yaml
name: 'Context7 Action Example'

on:
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.x'

      - name: Install dependencies
        run: pip install --upgrade pip && pip install -r requirements.txt

      - name: Run Context7 Action
        id: context7
        uses: rennf93/upsert-context@v1.0.0
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          repo: 'rennf93/some-repo'
          ref: 'main'
          workdir: './some-dir'
          log_level: 'debug'
          timeout: 600
          library_name: 'my-library'
          library_url: 'https://github.com/rennf93/some-library.git'
          library_branch: 'develop'

      - name: Use outputs
        run: |
          echo "Library added successfully: ${{ steps.context7.outputs.success }}"
          echo "Status code: ${{ steps.context7.outputs.code }}"
          echo "Message: ${{ steps.context7.outputs.message }}"
```

--------------------------------

### Full Example Workflow for Context7 Docs

Source: https://github.com/rennf93/upsert-context7/blob/master/README.md

This example demonstrates a complete GitHub Actions workflow that includes checking out code, updating Context7 documentation, and displaying the operation's results. It's triggered by new releases or manual dispatch.

```yaml
name: Update Context7 Docs

on:
  release:
    types: [ published ]
  workflow_dispatch:  # Manual trigger

jobs:
  update-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Update Context7 Documentation
        id: context7
        uses: rennf93/upsert-context7@v1
        with:
          operation: refresh

      - name: Show result
        run: |
          echo "Success: ${{ steps.context7.outputs.success }}"
          echo "Status: ${{ steps.context7.outputs.status-code }}"
          echo "Message: ${{ steps.context7.outputs.message }}"
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/rennf93/upsert-context7/blob/master/README.md

Installs the pre-commit framework and its associated hooks. This ensures that code quality checks are performed automatically before commits.

```bash
# Install pre-commit hooks
uv run pre-commit install
```

--------------------------------

### Constructor Initialization Example

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/MANIFEST.md

Demonstrates how to initialize the Context7Action class. Consider using this when setting up the action for the first time.

```python
action = Context7Action(
    token=os.environ.get("INPUT_TOKEN"),
    repo=os.environ.get("INPUT_REPO"),
    ref=os.environ.get("INPUT_REF"),
    workdir=os.environ.get("INPUT_WORKDIR"),
    log_level=os.environ.get("INPUT_LOG_LEVEL", "info"),
    timeout=int(os.environ.get("INPUT_TIMEOUT", 300)),
)
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/rennf93/upsert-context7/blob/master/README.md

Installs development dependencies required for testing and linting the project. This command should be run before other development tasks.

```bash
# Install dependencies
make install-dev
```

--------------------------------

### Add Library Example

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/MANIFEST.md

Shows how to add a library using the add_library method. This is useful when you need to include external dependencies for your action.

```python
success, code, message = action.add_library(
    name=os.environ.get("INPUT_LIBRARY_NAME"),
    url=os.environ.get("INPUT_LIBRARY_URL"),
    branch=os.environ.get("INPUT_LIBRARY_BRANCH", "main"),
)
```

--------------------------------

### YAML GitHub Actions Workflow for Enterprise GitHub Setup

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/GENERATION_REPORT.txt

This workflow demonstrates the setup required for using the project with Enterprise GitHub instances. It highlights specific configurations for secure connections.

```yaml
name: Enterprise GitHub Workflow

on: [push]

jobs:
  enterprise_job:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      - name: UpsertContext for Enterprise GitHub
        uses: ./ 
        with:
          github_url: "https://github.your-enterprise.com"
          github_token: ${{ secrets.ENTERPRISE_PAT }}
          input_param: "enterprise_config"
```

--------------------------------

### Example Usage of log_notice

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/api-reference/logging-methods.md

Demonstrates how to use the log_notice method to indicate successful action completion.

```python
action = Context7Action()

# In run() method when operation succeeds
action.log_notice("🎉 Action completed successfully!")
```

--------------------------------

### Example of Configuration Validation Failure

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/configuration.md

This example demonstrates a scenario where the 'repo-url' input is missing for an 'add' operation, triggering a validation failure.

```yaml
- uses: rennf93/upsert-context7@v1
  with:
    operation: add
    # Missing repo-url → validation fails
```

--------------------------------

### Add Library Request Payload Example

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/types.md

An example of a valid request payload for adding a library, including a sample GitHub repository URL.

```python
payload = {
    "docsRepoUrl": "https://github.com/myorg/mylib"
}
```

--------------------------------

### Bash Command Example: Checking Environment Variables

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/GENERATION_REPORT.txt

A simple Bash command to display environment variables. This is often used for debugging or verifying setup in CI/CD environments.

```bash
echo "Current environment variables:"
printenv | sort
```

--------------------------------

### Refresh Library Request Payload Example

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/types.md

An example of a valid request payload for refreshing a library, using the '/owner/repo' format.

```python
payload = {
    "requestedLibrary": "/myorg/mylib"
}
```

--------------------------------

### JSON Payload Example: Configuration Settings

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/GENERATION_REPORT.txt

An example JSON structure for configuration settings. This can be used to pass complex configurations to applications or services.

```json
{
  "settings": {
    "timeout": 300,
    "retries": 3,
    "log_level": "INFO"
  }
}
```

--------------------------------

### Run Method Example

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/MANIFEST.md

Demonstrates the basic usage of the run method to execute the action's primary logic. This is typically the last step in setting up and running the action.

```python
action.run()

```

--------------------------------

### Context7 Action Usage Example

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/endpoints.md

This Python code demonstrates how to use the Context7Action class to add a library, setting environment variables for the repository URL and timeout.

```python
action = Context7Action()
os.environ["INPUT_REPO_URL"] = "https://github.com/myorg/mylib"
os.environ["INPUT_TIMEOUT"] = "1800"

success, status_code, message = action.add_library()

if success:
    print(f"✅ Added: {message}")
else:
    print(f"❌ Error ({status_code}): {message}")
```

--------------------------------

### Configuration Resolution Result

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/configuration.md

Shows the resolved values after applying the precedence rules to the example configuration.

```text
operation = "add" (explicit)
library_name = "{GITHUB_REPOSITORY}" (auto-detected)
repo_url = "{GITHUB_SERVER_URL}/{GITHUB_REPOSITORY}" (auto-detected)
timeout = 1800 (default)
```

--------------------------------

### Workflow Configuration Example

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/configuration.md

Illustrates explicit input, auto-detection, and default value usage in workflow configuration. Empty fields trigger auto-detection or default resolution.

```yaml
with:
  operation: add  # Explicit → use "add"
  library-name: ""  # Empty → auto-detect from GITHUB_REPOSITORY
  # repo-url not provided → auto-detect from GITHUB_SERVER_URL + GITHUB_REPOSITORY
  timeout: ""  # Empty → use default 1800
```

--------------------------------

### Bash Command Example: Executing a Python Script

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/GENERATION_REPORT.txt

Demonstrates how to execute a Python script from the command line. This is a common pattern for running automation tasks.

```bash
python /path/to/your/script.py --input "some_value"
```

--------------------------------

### Project Directory Structure

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/MANIFEST.md

Illustrates the hierarchical organization of files and directories within the project. README.md is the starting point for documentation.

```markdown
```
/workspace/home/output/
│
├── README.md                          ← START HERE
├── INDEX.md                           ← Navigation guide
├── MANIFEST.md                        ← This file
│
├── configuration.md                   ← Inputs & environment
├── types.md                           ← Type definitions
├── endpoints.md                       ← API endpoints
├── errors.md                          ← Error handling
│
└── api-reference/
    ├── Context7Action.md              ← Main class
    ├── logging-methods.md             ← Logging API
    └── validation-and-output.md       ← Validation/output
```
```

--------------------------------

### Python Type Conversion Example

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/GENERATION_REPORT.txt

Shows how to perform type conversions, such as converting environment variables to integers. This is useful for ensuring correct data types for configuration.

```python
import os

def get_int_env_var(var_name, default=0):
    value = os.getenv(var_name)
    if value is None:
        return default
    try:
        return int(value)
    except ValueError:
        print(f"Warning: Environment variable {var_name} is not a valid integer. Using default.")
        return default

# Example usage
timeout_seconds = get_int_env_var("CUSTOM_TIMEOUT", 60)
```

--------------------------------

### Python Class Instantiation Example

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/GENERATION_REPORT.txt

Demonstrates basic class instantiation in Python. This is a fundamental pattern for using the project's classes.

```python
from upsert_context import UpsertContext

# Instantiate with default settings
ctx = UpsertContext()

# Instantiate with specific configuration (example)
ctx_custom = UpsertContext(config_path="/path/to/config.yaml")
```

--------------------------------

### Full Workflow Example for Context7Action

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/api-reference/Context7Action.md

Demonstrates the complete process of using Context7Action to refresh a library. This includes setting environment variables for inputs, instantiating the action, validating inputs, executing the refresh operation, and setting the output based on the result. Ensure each thread uses its own instance as the class is not thread-safe.

```python
#!/usr/bin/env python3
import os
from src.main import Context7Action

# Set inputs (normally from GitHub Actions environment)
os.environ["INPUT_OPERATION"] = "refresh"
os.environ["INPUT_LIBRARY_NAME"] = "/myorg/mylib"
os.environ["INPUT_TIMEOUT"] = "1800"

# Create and run action
action = Context7Action()

# Validate before running
if not action.validate_inputs():
    print("Invalid configuration")
    exit(1)

# Execute operation
success, status, message = action.refresh_library()

# Handle result
action.set_output("success", str(success).lower())
action.set_output("status-code", str(status))
action.set_output("message", message)

if success:
    print("✅ Documentation refreshed")
else:
    print(f"❌ Failed: {message}")

```

--------------------------------

### Python File I/O Handling Example

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/GENERATION_REPORT.txt

Illustrates basic file input/output operations within a Python script. This pattern is used for reading configuration files or writing output.

```python
def read_file_content(filepath):
    try:
        with open(filepath, 'r') as f:
            return f.read()
    except FileNotFoundError:
        print(f"Error: File not found at {filepath}")
        return None

content = read_file_content("config.json")
```

--------------------------------

### Context7 Workflow Example

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/endpoints.md

This YAML snippet shows how to configure a GitHub Actions workflow to use the rennf93/upsert-context7 action to add a library.

```yaml
- name: Add to Context7
  uses: rennf93/upsert-context7@v1
  with:
    operation: add
    repo-url: https://github.com/myorg/mylib
    timeout: 1800
```

--------------------------------

### Python add_library() Usage Example

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/GENERATION_REPORT.txt

Shows how to use the add_library() function to add a new library. This function is essential for managing project dependencies.

```python
from upsert_context import UpsertContext

ctx = UpsertContext()

# Add a library with default settings
success, status_code, message = ctx.add_library("new_library_name")

# Add a library with specific version and options
success, status_code, message = ctx.add_library("another_library", version="1.2.3", force=True)
```

--------------------------------

### Workflow Integration Example

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/api-reference/logging-methods.md

A YAML configuration for a GitHub Actions workflow that uses the upsert-context7 action. This demonstrates how the action integrates into a CI/CD pipeline.

```yaml
name: Update Context7

on: [release]

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Update Documentation
        uses: rennf93/upsert-context7@v1
        with:
          operation: refresh

      # Logs appear here with emojis and annotations
```

--------------------------------

### Python Logging Methods Example

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/GENERATION_REPORT.txt

Illustrates the use of various logging methods provided by the system. These methods correspond to different log levels for detailed event tracking.

```python
from upsert_context import UpsertContext

ctx = UpsertContext()

ctx.log_info("This is an informational message.")
ctx.log_success("Operation completed successfully.")
ctx.log_warning("A potential issue was detected.")
ctx.log_error("An error occurred during processing.")
ctx.log_notice("Important system notice.")
```

--------------------------------

### Python Usage Example for Refresh Library Action

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/endpoints.md

Demonstrates how to use the Context7Action class to refresh a library. It sets environment variables for the library name and timeout, then calls the refresh_library method and prints the outcome.

```python
action = Context7Action()
os.environ["INPUT_LIBRARY_NAME"] = "/myorg/mylib"
os.environ["INPUT_TIMEOUT"] = "1800"

success, status_code, message = action.refresh_library()

if success:
    print(f"✅ Refresh started: {message}")
else:
    print(f"❌ Error ({status_code}): {message}")
```

--------------------------------

### Python set_output() Usage Example

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/GENERATION_REPORT.txt

Shows how to use the set_output() function to define output variables for workflows. This is used to pass data between workflow steps.

```python
from upsert_context import UpsertContext

ctx = UpsertContext()

# Set a simple string output
ctx.set_output("output_key", "output_value")

# Set a JSON output (example)
json_output = {"status": "success", "data": [1, 2, 3]}
ctx.set_output("json_output_key", json_output)
```

--------------------------------

### Set Message Output

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/api-reference/validation-and-output.md

Sets the 'message' output variable to 'Library added successfully'. This example demonstrates setting a string message.

```python
action.set_output("message", "Library added successfully")
# Writes to GITHUB_OUTPUT: message=Library added successfully
```

--------------------------------

### Stacking Logs for Debugging

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/api-reference/logging-methods.md

Provides an example of how to stack multiple log messages to form a complete picture for debugging, including operation details, inputs, and error messages.

```python
# Good - logs form complete picture
action.log_info(f"Operation: {operation}")
action.log_info(f"Inputs: {library_name}, {repo_url}")
success, status, msg = action.refresh_library()
if not success:
    action.log_error(f"Failed: {msg}")
```

--------------------------------

### Set Success Status Output

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/api-reference/validation-and-output.md

Sets the 'success' output variable to 'true'. This example demonstrates setting a boolean status.

```python
action = Context7Action()
action.set_output("success", "true")
# Writes to GITHUB_OUTPUT: success=true
```

--------------------------------

### Python Type Hinting Examples

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/INDEX.md

Demonstrates the use of type hints for public methods in Python. Ensure all public methods include complete type hints for clarity and maintainability.

```python
def validate_inputs(self) -> bool:
    ...
```

```python
def set_output(self, name: str, value: str) -> None:
    ...
```

```python
def refresh_library(self) -> tuple[bool, int, str]:
    ...
```

--------------------------------

### Python refresh_library() Usage Example

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/GENERATION_REPORT.txt

Illustrates the usage of the refresh_library() function to update existing libraries. Use this when library versions need to be synchronized.

```python
from upsert_context import UpsertContext

ctx = UpsertContext()

# Refresh a library to its latest version
success, status_code, message = ctx.refresh_library("existing_library")

# Refresh a library to a specific version
success, status_code, message = ctx.refresh_library("another_library", version="4.5.6")
```

--------------------------------

### Add Library Error Response Example

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/endpoints.md

For other HTTP 400 errors, such as an invalid repository URL, the API returns an error message.

```json
{
  "message": "Invalid repository URL"
}
```

--------------------------------

### YAML GitHub Actions Workflow with Full Configuration

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/GENERATION_REPORT.txt

An example of a GitHub Actions workflow with comprehensive configuration options. This showcases advanced settings for fine-grained control.

```yaml
name: Full Config Workflow

on: [push]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      - name: UpsertContext with Full Config
        uses: ./ 
        with:
          input_param_1: "value1"
          input_param_2: "value2"
          env_var_1: "env_value1"
          config_path: ".github/config.yaml"
```

--------------------------------

### Operation Result Tuple Example

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/types.md

Demonstrates how to unpack and check the success status of an operation result tuple. Handles both success and failure cases.

```python
success, status_code, message = action.refresh_library()

if success:
    print(f"Success (HTTP {status_code}): {message}")
else:
    print(f"Failed (HTTP {status_code}): {message}")
```

--------------------------------

### Typical Section Structure

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/MANIFEST.md

Defines the standard layout for method or topic sections, including overview, signature, parameters, returns, description, examples, and notes.

```markdown
1. **Overview** — One-sentence summary
2. **Signature** — Fenced code block with exact signature
3. **Parameters** — Table with name, type, required, description
4. **Returns** — Return type and meaning
5. **Description** — Detailed explanation of behavior
6. **Examples** — 1-3 practical code examples
7. **Notes** — Implementation details or caveats
```

--------------------------------

### Configure Action with Secrets

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/configuration.md

Example of how to configure the upsert-context7 action using secrets for sensitive inputs like library name and repository URL.

```yaml
- uses: rennf93/upsert-context7@v1
  with:
    operation: refresh
    library-name: ${{ secrets.CONTEXT7_LIBRARY_NAME }}
    repo-url: ${{ secrets.CONTEXT7_REPO_URL }}
```

--------------------------------

### GitHub Actions Workflow Example for Refreshing Library

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/endpoints.md

This YAML snippet shows how to configure a GitHub Actions workflow to refresh Context7 documentation. It specifies the 'refresh' operation and provides the library name and timeout as inputs.

```yaml
- name: Refresh Context7 Documentation
  uses: rennf93/upsert-context7@v1
  with:
    operation: refresh
    library-name: /myorg/mylib
    timeout: 1800
```

--------------------------------

### YAML GitHub Actions Workflow with Matrix Strategies

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/GENERATION_REPORT.txt

An example of using matrix strategies in GitHub Actions to run jobs across different configurations. This is useful for testing against multiple environments.

```yaml
name: Matrix Strategy Workflow

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [14, 16, 18]
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}
      - name: Run UpsertContext
        uses: ./ 
        with:
          input_param: "matrix_test"
```

--------------------------------

### Add Library Success Response Example

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/endpoints.md

A successful response from the add library endpoint will return an HTTP status code between 200-202 and a JSON body confirming the action.

```json
{
  "message": "Library added successfully. Documentation parsing has started."
}
```

--------------------------------

### Add library with custom enterprise GitHub URL

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/configuration.md

Configure the 'repo-url' for adding a library when using an enterprise GitHub instance. This example sets the GITHUB_SERVER_URL environment variable.

```yaml
env:
  GITHUB_SERVER_URL: https://github.enterprise.com

- uses: rennf93/upsert-context7@v1
  with:
    operation: add
    repo-url: https://github.enterprise.com/myorg/mylib
```

--------------------------------

### Add Library Already Exists Response Example

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/endpoints.md

If the project already exists, the API returns an HTTP 400 status code but with a message indicating it already exists, which is treated as a success.

```json
{
  "message": "The project already exists."
}
```

--------------------------------

### Python Error Handling Example

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/GENERATION_REPORT.txt

Demonstrates a common pattern for handling errors that may occur during library operations. This includes checking return values and logging issues.

```python
from upsert_context import UpsertContext

ctx = UpsertContext()

try:
    success, status_code, message = ctx.add_library("problematic_library")
    if not success:
        ctx.log_error(f"Failed to add library: {message} (Status: {status_code})")
except Exception as e:
    ctx.log_error(f"An unexpected error occurred: {e}")
```

--------------------------------

### Basic YAML GitHub Actions Workflow

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/GENERATION_REPORT.txt

A simple GitHub Actions workflow demonstrating basic usage. This serves as a starting point for integrating the project into CI/CD pipelines.

```yaml
name: Basic Workflow

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      - name: Run UpsertContext
        uses: ./ 
        with:
          input_param: "some_value"
```

--------------------------------

### Bash Command Example: Git Clone

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/GENERATION_REPORT.txt

A standard Bash command for cloning a Git repository. This is frequently used in CI/CD pipelines to fetch source code.

```bash
git clone https://github.com/user/repo.git --branch main --single-branch
```

--------------------------------

### Main Entry Point

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/api-reference/Context7Action.md

The `main()` function serves as the entry point for the application. It initializes and runs the `Context7Action`.

```APIDOC
## main()

### Description
Entry point function that creates a `Context7Action` instance and runs it.

### Returns
`None`

### Throws
`SystemExit` (from `Context7Action.run()`)

### Example
```python
from src.main import main

if __name__ == "__main__":
    main()
```
```

--------------------------------

### YAML GitHub Actions Workflow for Error Handling

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/GENERATION_REPORT.txt

An example workflow illustrating error handling strategies in GitHub Actions. This setup helps in managing and responding to failures gracefully.

```yaml
name: Error Handling Workflow

concurrency: docs

on:
  push:
    branches: [ main ]
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.x'
      - name: Install dependencies
        run: pip install flake8
      - name: Lint with flake8
        run: flake8 src --count --show-source --statistics
        # If flake8 runs into an error, the workflow will fail here
      - name: Run UpsertContext (example of potential failure)
        uses: ./ 
        with:
          input_param: "trigger_error_if_possible"
```

--------------------------------

### Curl Request Example for Refresh Library

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/endpoints.md

Use this cURL command to send a POST request to refresh a library. Ensure the Content-Type is set to application/json and the request body contains the 'requestedLibrary' identifier.

```bash
curl -X POST https://context7.com/refresh-library \
  -H "Content-Type: application/json" \
  -d '{"requestedLibrary": "/myorg/mylib"}'
```

--------------------------------

### Context7Action Constructor Initialization

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/api-reference/Context7Action.md

Initializes a Context7Action instance by reading configuration from environment variables. Supports auto-detection for library name and repository URL if not explicitly provided.

```python
def __init__(self) -> None:
    """Handler for Context7 API operations"""
```

```python
import os

os.environ["INPUT_OPERATION"] = "refresh"
os.environ["INPUT_LIBRARY_NAME"] = "/myorg/mylib"
os.environ["INPUT_TIMEOUT"] = "600"

action = Context7Action()
assert action.operation == "refresh"
assert action.library_name == "/myorg/mylib"
assert action.timeout == 600
```

--------------------------------

### JSON Payload Example: Complex Data Structure

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/GENERATION_REPORT.txt

An example of a more complex JSON structure, potentially representing nested data or lists. Useful for structured data exchange.

```json
{
  "id": "task-123",
  "metadata": {
    "source": "api",
    "timestamp": "2023-10-27T10:00:00Z"
  },
  "results": [
    {"metric": "cpu_usage", "value": 0.85},
    {"metric": "memory_usage", "value": 0.60}
  ]
}
```

--------------------------------

### Network Error Messages

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/errors.md

Examples of network-related errors that can occur during communication with the server.

```text
❌ Request failed: Connection refused
❌ Request failed: Read timed out after 1s
❌ Request failed: SSL certificate verify failed
```

--------------------------------

### Initialize Context7 Action

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/INDEX.md

Instantiate the Context7Action class to begin using its methods.

```python
action = Context7Action()
```

--------------------------------

### String Parameter Types

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/types.md

Defines the constraints and examples for various string parameters used across the API.

```APIDOC
## String Parameters

### Description
These parameters accept string values with specific formatting or content requirements.

| Parameter | Constraints | Examples |
|-----------|-------------|----------|
| `library_name` | Format: `/owner/repo`, starts with `/` | `/myorg/mylib`, `/facebook/react` |
| `repo_url` | Valid HTTPS URL | `https://github.com/myorg/mylib` |
| `message` (logging) | Any string | Error messages, status updates |
| `name` (output) | GitHub Actions variable name | `"success"`, `"status-code"` |
| `value` (output) | Any string | `"true"`, `"200"`, `"Error message"` |
```

--------------------------------

### Validation Error Messages

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/errors.md

Examples of validation errors that occur when input parameters are incorrect or missing for specific operations.

```text
❌ Invalid operation: delete. Must be 'add' or 'refresh'
❌ repo-url is required for 'add' operation
❌ library-name is required for 'refresh' operation
```

--------------------------------

### Add Library Request Flow

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/endpoints.md

Demonstrates the sequence for adding a library to Context7, including the POST request format and expected server response.

```text
1. POST https://context7.com/api/v1/add
   {"docsRepoUrl": "https://github.com/myorg/mylib"}

2. Server receives request, starts async parsing

3. Response (HTTP 200/201/202):
   {"message": "Library added successfully"}

4. Action returns:
   (True, 200, "Library added successfully")
```

--------------------------------

### Run Context7Action Entry Point

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/api-reference/Context7Action.md

This is the main entry point for running the Context7Action. It should be called when the script is executed directly.

```python
from src.main import main

if __name__ == "__main__":
    main()
```

--------------------------------

### Main Module Execution

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/INDEX.md

Entry point for the module's execution.

```python
main() -> None
```

--------------------------------

### API Error Messages

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/errors.md

Examples of API errors, including HTTP status codes, indicating issues with the request or server-side problems.

```text
❌ API error (HTTP 400): Invalid repository URL
❌ API error (HTTP 404): Library not found
❌ API error (HTTP 500): Internal Server Error
```

--------------------------------

### Setting 'message' Output in Python

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/api-reference/validation-and-output.md

Demonstrates setting the 'message' output with various string values, including an empty string.

```python
# Any string message
action.set_output("message", "Success message")
action.set_output("message", "Error: Bad request")
action.set_output("message", "")  # Empty string is valid
```

--------------------------------

### Configure Action with Matrix Strategy

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/configuration.md

Demonstrates using a GitHub Actions matrix strategy to run the upsert-context7 action for multiple libraries defined in the matrix.

```yaml
strategy:
  matrix:
    library:
      - {name: "/org/lib1", url: "https://github.com/org/lib1"}
      - {name: "/org/lib2", url: "https://github.com/org/lib2"}

steps:
  - uses: rennf93/upsert-context7@v1
    with:
      operation: refresh
      library-name: ${{ matrix.library.name }}
      repo-url: ${{ matrix.library.url }}
```

--------------------------------

### Enable Verbose Output for Debugging

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/errors.md

Set environment variables for INPUT_OPERATION and INPUT_LIBRARY_NAME, then instantiate and run the Context7Action to log detailed information during the refresh operation.

```python
import os
from src.main import Context7Action

os.environ["INPUT_OPERATION"] = "refresh"
os.environ["INPUT_LIBRARY_NAME"] = "/myorg/mylib"

action = Context7Action()
action.log_info("Starting operation...")

success, status_code, message = action.refresh_library()

print(f"Success: {success}")
print(f"Status Code: {status_code}")
print(f"Message: {message}")
```

--------------------------------

### JSON Payload Example: Status Update

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/GENERATION_REPORT.txt

A JSON payload indicating the status of an ongoing process. This can be used for real-time updates or reporting.

```json
{
  "status": "processing",
  "progress": 75,
  "current_step": "Validating data"
}
```

--------------------------------

### Using Appropriate Log Levels

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/api-reference/logging-methods.md

Demonstrates the correct usage of log levels for different scenarios: info for general flow, success for completed operations, and error for failures.

```python
# Good - use info for general flow
action.log_info("Processing library")

# Good - use success when operation succeeds
action.log_success("Library added")

# Good - use error for failures
action.log_error("Failed to add library")
```

--------------------------------

### Error Handling

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/GENERATION_REPORT.txt

Comprehensive guide to error handling, including validation errors, API errors, network issues, and recovery strategies.

```APIDOC
## Error Handling

This section outlines the various error handling mechanisms and patterns supported by the Upsert-Context7 API.

### Validation Error Patterns

Details on 5 distinct types of validation errors, including their causes and potential resolutions.

### API Error Scenarios

Specific error scenarios that can occur during API operations, documented per endpoint.

### Network Error Handling

Strategies for handling network-related errors, including retry logic and timeouts.

### File I/O Error Handling

Guidance on managing errors that may occur during file input/output operations.

### Error Recovery Strategies

Methods and patterns for recovering from various error conditions to ensure workflow robustness.

### Debugging Patterns

Techniques and best practices for debugging issues encountered within the API and its integrations.
```

--------------------------------

### Minimal Configuration with Auto-Detection

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/configuration.md

Use this minimal configuration when auto-detection of repository details is sufficient. The action automatically detects `library-name`, `repo-url`, and uses a default `timeout`.

```yaml
name: Update Context7 Docs

on:
  release:
    types: [published]

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Update Context7 Documentation
        uses: rennf93/upsert-context7@v1
        with:
          operation: refresh
```

--------------------------------

### Set HTTP Status Code Output

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/api-reference/validation-and-output.md

Sets the 'status-code' output variable to '200'. This example shows setting a numerical status code.

```python
action.set_output("status-code", "200")
# Writes to GITHUB_OUTPUT: status-code=200
```

--------------------------------

### JSON Payload Example: Error Response

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/GENERATION_REPORT.txt

A typical JSON format for an API error response. It includes details about the error for debugging and handling.

```json
{
  "error": {
    "code": "INVALID_INPUT",
    "message": "The provided input parameter is missing.",
    "details": "Parameter 'required_field' was not found."
  }
}
```

--------------------------------

### GitHub Actions: Reading Inputs

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/api-reference/Context7Action.md

Demonstrates how to use the Context7Action as a GitHub Action and pass inputs. Inputs are read as environment variables prefixed with INPUT_.

```yaml
- uses: rennf93/upsert-context7@v1
  with:
    operation: refresh
    library-name: "/myorg/mylib"
    timeout: 1800
```

--------------------------------

### Setting 'success' Output in Python

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/api-reference/validation-and-output.md

Shows how to set the 'success' output, ensuring boolean values are converted to lowercase strings ('true' or 'false').

```python
# True becomes "true" (string)
action.set_output("success", str(True).lower())  # "true"

# False becomes "false" (string)
action.set_output("success", str(False).lower())  # "false"
```

--------------------------------

### Python validate_inputs() Usage Example

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/GENERATION_REPORT.txt

Demonstrates how to use the validate_inputs() function to check input parameters. This function is crucial for ensuring data integrity before processing.

```python
from upsert_context import UpsertContext

ctx = UpsertContext()

# Validate inputs against default rules
validation_errors = ctx.validate_inputs()

# Validate inputs with custom data
custom_data = {"key": "value"}
validation_errors = ctx.validate_inputs(data=custom_data)
```

--------------------------------

### Context7Action Timeout Configuration

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/api-reference/Context7Action.md

Configures the timeout for all HTTP requests made by Context7Action by setting the INPUT_TIMEOUT environment variable. This example sets the timeout to 10 seconds.

```python
import os
from src.context7 import Context7Action

os.environ["INPUT_TIMEOUT"] = "10"  # 10 seconds
action = Context7Action()
# All requests will timeout after 10 seconds
```

--------------------------------

### Setting 'status-code' Output in Python

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/api-reference/validation-and-output.md

Illustrates setting the 'status-code' output by converting integer status codes to strings.

```python
# Integer status codes become strings
action.set_output("status-code", str(200))   # "200"
action.set_output("status-code", str(404))   # "404"
action.set_output("status-code", str(0))     # "0" (network error)
```

--------------------------------

### JSON Payload Example: Basic Request Body

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/GENERATION_REPORT.txt

A sample JSON payload representing a basic request body. This format is commonly used for API interactions.

```json
{
  "operation": "add",
  "library": "example-lib",
  "version": "1.0.0"
}
```

--------------------------------

### Run Tests

Source: https://github.com/rennf93/upsert-context7/blob/master/README.md

Executes the project's test suite. This command is used to verify the functionality and reliability of the action.

```bash
# Run tests
make test
```

--------------------------------

### Sample Output of Workflow Integration

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/api-reference/logging-methods.md

Presents a sample of the log output generated when the upsert-context7 action runs within a GitHub Actions workflow. It shows the format and content of the logs.

```text
💡 🚀 Starting Upsert Context7 action
💡 Operation: refresh
💡 Library name: /myorg/mylib
💡 Repository URL: https://github.com/myorg/mylib
💡 Request timeout: 1800 seconds (30 minutes)
✅ Documentation refresh successful: Refresh process started successfully
📢 Status: processing
📢 🎉 Action completed successfully!
```

--------------------------------

### Perform 'add' operation

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/configuration.md

Use this snippet to register a new library with Context7. Ensure the 'operation' parameter is set to 'add'.

```yaml
- uses: rennf93/upsert-context7@v1
  with:
    operation: add
```

--------------------------------

### Add Library Operation

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/INDEX.md

Add a new library to Context7. Requires setting environment variables for operation and repository URL. Returns success status, status code, and a message.

```python
os.environ["INPUT_OPERATION"] = "add"
os.environ["INPUT_REPO_URL"] = "https://github.com/myorg/mylib"

action = Context7Action()
success, status, message = action.add_library()
```

--------------------------------

### Lint Code with Make

Source: https://github.com/rennf93/upsert-context7/blob/master/README.md

Runs the linting process using the `make lint` command. This is a shortcut for checking code quality according to project standards.

```bash
# Or use make commands
make lint  # Check code quality
```

--------------------------------

### Repository URL Detection Logic

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/configuration.md

Explains how the 'repo-url' input is determined, using the GitHub repository and server URL when not explicitly provided.

```text
If INPUT_REPO_URL is empty AND GITHUB_REPOSITORY is set:
  repo_url = GITHUB_SERVER_URL + "/" + GITHUB_REPOSITORY

If INPUT_REPO_URL is empty AND GITHUB_REPOSITORY is empty:
  repo_url = "" (empty)

Otherwise:
  repo_url = INPUT_REPO_URL
```

--------------------------------

### Add Library Endpoint

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/MANIFEST.md

Documentation for the endpoint used to add a library. It includes details on the URL, method, content type, request/response schemas, status codes, and usage examples.

```APIDOC
## POST /libraries

### Description
Adds a new library to the system.

### Method
POST

### Endpoint
/libraries

### Parameters
#### Request Body
- **operation** (string) - Required - The operation to perform.
- **library-name** (string) - Required - The name of the library.
- **repo-url** (string) - Required - The URL of the repository for the library.
- **timeout** (integer) - Optional - The timeout in seconds for the operation.

### Request Example
{
  "operation": "add",
  "library-name": "example-lib",
  "repo-url": "https://github.com/example/example-lib.git",
  "timeout": 60
}

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.
- **message** (string) - A message describing the result of the operation.

#### Response Example
{
  "status": "success",
  "message": "Library added successfully."
}
```

--------------------------------

### Context7Action Class Methods

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/INDEX.md

Documentation for the Context7Action class, including its constructor, operation methods, validation, output, and execution methods.

```APIDOC
## Context7Action Class

### Description
Complete class documentation for managing Context7 operations.

### Methods
- **Constructor and initialization**: Initializes the Context7Action.
- **`add_library()`**: Adds a library.
- **`refresh_library()`**: Refreshes a library.
- **`validate_inputs()`**: Validates required inputs.
- **`set_output()`**: Writes GitHub Actions outputs.
- **`run()`**: Executes the action.
- **`main()`**: Main execution entry point.
```

--------------------------------

### Full Configuration with Explicit Values

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/configuration.md

This configuration explicitly defines all parameters, including `library-name`, `repo-url`, and `timeout`. It is suitable for scenarios requiring precise control over the action's behavior and integrates with manual workflow triggers.

```yaml
name: Update Context7 Docs

on:
  workflow_dispatch:
    inputs:
      operation:
        description: 'Operation: add or refresh'
        required: true
        default: 'refresh'

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Update Context7 Documentation
        id: context7
        uses: rennf93/upsert-context7@v1
        with:
          operation: ${{ github.event.inputs.operation }}
          library-name: /myorg/mylib
          repo-url: https://github.com/myorg/mylib
          timeout: 1800

      - name: Show results
        run: |
          echo "Success: ${{ steps.context7.outputs.success }}"
          echo "Status: ${{ steps.context7.outputs.status-code }}"
          echo "Message: ${{ steps.context7.outputs.message }}"
```

--------------------------------

### Basic Usage of Upsert Context7 Action

Source: https://github.com/rennf93/upsert-context7/blob/master/README.md

This snippet shows the basic configuration to refresh documentation using the action. It's suitable for simple update scenarios.

```yaml
name: Update Context7 Documentation
uses: rennf93/upsert-context7@v1
with:
  operation: refresh
```

--------------------------------

### Test Network Connectivity to Context7

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/errors.md

Use the requests library to perform a GET request to the Context7 domain with a timeout. This helps diagnose issues related to network reachability or service availability.

```python
import requests

try:
    response = requests.get("https://context7.com", timeout=5)
    print(f"✅ Can reach Context7 (HTTP {response.status_code})")
except requests.RequestException as e:
    print(f"❌ Cannot reach Context7: {e}")
```

--------------------------------

### GitHub Actions: Setting Outputs

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/api-reference/Context7Action.md

Shows how to use the Context7Action in a GitHub Action workflow and access its outputs in subsequent steps. Outputs are written to GITHUB_OUTPUT.

```yaml
- id: context7
  uses: rennf93/upsert-context7@v1
  with:
    operation: refresh

- run: |
    echo "Success: ${{ steps.context7.outputs.success }}"
    echo "Status: ${{ steps.context7.outputs.status-code }}"
    echo "Message: ${{ steps.context7.outputs.message }}"
```

--------------------------------

### GitHub Actions Integration

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/api-reference/Context7Action.md

Demonstrates how to use Context7Action as a GitHub Action, including setting inputs and handling outputs.

```APIDOC
## Integration with GitHub Actions

### Reading Inputs
```yaml
- uses: rennf93/upsert-context7@v1
  with:
    operation: refresh
    library-name: "/myorg/mylib"
    timeout: 1800
```

These are passed as:
- `INPUT_OPERATION` environment variable
- `INPUT_LIBRARY_NAME` environment variable
- `INPUT_TIMEOUT` environment variable

### Setting Outputs

The action writes to `GITHUB_OUTPUT`, which makes values available to subsequent steps:

```yaml
- id: context7
  uses: rennf93/upsert-context7@v1
  with:
    operation: refresh

- run: |
    echo "Success: ${{ steps.context7.outputs.success }}"
    echo "Status: ${{ steps.context7.outputs.status-code }}"
    echo "Message: ${{ steps.context7.outputs.message }}"
```
```

--------------------------------

### Python Request Example for Refresh Library

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/endpoints.md

This Python script uses the 'requests' library to send a POST request to the refresh-library endpoint. It includes a timeout of 1800 seconds, recommended for potentially long-running operations.

```python
import requests

payload = {"requestedLibrary": "/myorg/mylib"}
response = requests.post(
    "https://context7.com/refresh-library",
    json=payload,
    timeout=1800
)
```

--------------------------------

### Add Operation for New Libraries

Source: https://github.com/rennf93/upsert-context7/blob/master/README.md

This snippet configures the action to add a new library to Context7. It specifies the 'add' operation and an optional repository URL. Auto-detection is used if `repo-url` is omitted.

```yaml
- uses: rennf93/upsert-context7@v1
  with:
    operation: add
    repo-url: "https://github.com/owner/repo"  # Optional, auto-detected
```

--------------------------------

### Handle Missing GITHUB_OUTPUT Environment Variable

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/errors.md

If the GITHUB_OUTPUT environment variable is not set, the action defaults to using the legacy ::set-output command syntax.

```python
# Don't set GITHUB_OUTPUT
action = Context7Action()
action.set_output("key", "value")
# Prints: ::set-output name=key::value
```

--------------------------------

### Add Library Endpoint Request (Python)

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/endpoints.md

This Python script uses the requests library to send a POST request to the add library endpoint. Ensure the 'requests' library is installed. The timeout is set to 1800 seconds.

```python
import requests

payload = {"docsRepoUrl": "https://github.com/myorg/mylib"}
response = requests.post(
    "https://context7.com/api/v1/add",
    json=payload,
    timeout=1800
)
```

--------------------------------

### Add Library: Already Exists (HTTP 400)

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/errors.md

Handles the specific case where the library being added already exists in the Context7 system.

```APIDOC
## Add Library: Already Exists (HTTP 400)

### Description
Handles the specific case where the library being added already exists in the Context7 system. This is treated as a success scenario as the desired end state is achieved.

### Condition
Response message contains "already exists" (case-insensitive).

### Return Value
- `(True, 400, message)`: Indicates the library already exists.

### Message Pattern
"The project already exists"

### Source
`add_library()` method, lines 128-130
```

--------------------------------

### Refresh Library Request Flow

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/endpoints.md

Illustrates the process for initiating a library refresh in Context7, detailing the POST request, server queuing, and the initial response.

```text
1. POST https://context7.com/refresh-library
   {"requestedLibrary": "/myorg/mylib"}

2. Server receives request, queues refresh task

3. Response (HTTP 200):
   {"message": "Refresh started", "status": "processing"}

4. Action returns:
   (True, 200, "Refresh started")
```

--------------------------------

### Legacy Output Syntax for Older Runners

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/api-reference/validation-and-output.md

Prints the legacy `::set-output name=...::...` syntax, which older GitHub Actions runners parse from stdout, used when GITHUB_OUTPUT is not set or file write fails.

```python
print(f"::set-output name={name}::{value}")
```

--------------------------------

### Context7Action Class Methods

Source: https://github.com/rennf93/upsert-context7/blob/master/_autodocs/MANIFEST.md

Reference for the Context7Action class, including its constructor and various methods for logging, validation, and library management.

```APIDOC
## Class: Context7Action

### Description
Provides a complete reference for the Context7Action class, detailing its initialization, methods, and integration points.

### Constructor
#### `__init__()`
Initializes a new instance of the Context7Action class. Supports auto-detection logic, timeout handling, and instance attribute configuration.

### Methods
#### `set_output(name, value)`
Sets an output for the action. Handles file operations for modern runners and provides fallback behavior for older runners. Supports various output types including boolean, status code, and message.

#### `log_info(message)`
Logs an informational message.

#### `log_success(message)`
Logs a success message.

#### `log_warning(message)`
Logs a warning message. Integrates with GitHub Actions for warning annotations.

#### `log_error(message)`
Logs an error message. Integrates with GitHub Actions for error annotations.

#### `log_notice(message)`
Logs a notice message. Integrates with GitHub Actions for notice annotations.

#### `validate_inputs()`
Validates the inputs provided to the action. Returns a boolean indicating success or failure. Includes validation rules for operation type, repo-url, and library-name. Provides example code for usage.

#### `add_library()`
Adds a library. Returns a tuple indicating success status, an integer code, and a string message. Details success and error scenarios with an example.

#### `refresh_library()`
Refreshes a library. Returns a tuple indicating success status, an integer code, and a string message. Details success and error scenarios with an example.

#### `run()`
Executes the main workflow of the action. Includes lifecycle description, exception handling, and an example of its usage.
```