Metadata-Version: 2.4
Name: gasket-cli
Version: 0.2.4
Summary: Run GitHub Actions locally using nektos/act from a Python CLI
Author-email: hieu_trincao <kaiinredtie@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/hieupham259/gasket
Project-URL: Repository, https://github.com/hieupham259/gasket
Project-URL: Issues, https://github.com/hieupham259/gasket/issues
Keywords: github-actions,act,ci,local,docker,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# gasket-cli

gasket-cli is a cross-platform Python CLI for running GitHub Actions locally with
[nektos/act](https://github.com/nektos/act). It wraps the `act` binary, helps set
up prerequisites, and now includes the first stage of an LLM configuration layer
for selecting modes, providers, models, and credential references.

Current package version: `0.2.3`

## What Works Today

- Run GitHub Actions workflows locally through `gasket run-act`.
- Check, install, and uninstall `act` through `gasket setup`.
- Switch between LLM modes with `gasket llm-mode`.
- Persist and validate provider/model selections with `gasket config`.
- Resolve the active LLM configuration through the internal registry and factory layer.

## Prerequisites

- Python `3.10+`
- Docker installed and running
- `act` installed locally, or installed through `gasket setup install-act`

## Installation

### Local development install

```bash
git clone <repo-url>
cd gasket
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

On Windows:

```bash
.venv\Scripts\activate
```

## Commands

### `gasket run-act`

Run GitHub Actions workflows locally using `act`.

```bash
gasket run-act
gasket run-act --event pull_request
gasket run-act --list
gasket run-act --dry-run
gasket run-act -j test
gasket run-act -W .github/workflows/ci.yml
gasket run-act -s MY_SECRET=value
gasket run-act --secret-file .secrets
gasket run-act --env-file .env
gasket run-act -P ubuntu-latest=node:18-bullseye
```

Key capabilities:

- workflow and job targeting
- event selection
- secrets, vars, inputs, env files, and event payload files
- dry-run and list-only modes
- offline runs, matrix filters, and timeout control

### `gasket setup`

Manage installation and prerequisite checks.

```bash
gasket setup check
gasket setup check --format json
gasket setup install-act
gasket setup install-act --install-dir ~/.local/bin --force
gasket setup install-all
gasket setup uninstall-act
```

### `gasket llm-mode`

Switch the active LLM mode interactively.

Supported modes today:

- `local`
- `api_provider`
- `llm_api_key`

The command persists the selected mode and resets that mode to a valid default
provider/model pair.

```bash
gasket llm-mode
```

### `gasket config`

Manage the LLM configuration surface.

```bash
gasket config path
gasket config list-models
gasket config list-models anthropic
gasket config set-model qwen2.5-coder
gasket config use-provider anthropic
gasket config set-key openai sk-example
gasket config set-api-provider cloudflare-default
gasket config set-api-key cf-example
```

Current provider metadata in the registry:

- Local mode: `ollama`
- Managed API mode: `cloudflare-default`
- BYOK mode: `openai`, `anthropic`, `gemini`, `mistral`

Generic legacy config commands have been removed. The supported `config`
subcommands are now focused on the LLM configuration model only.

## Current LLM Scope

The LLM part of the project is currently a configuration and validation layer,
not a full inference client surface.

Implemented today:

- provider registry and allowlisted model metadata
- mode-aware config schema and default resolution
- credential reference persistence
- active configuration validation through `resolve_llm()`
- abstract provider interface definitions

Not exposed as end-user commands yet:

- concrete provider clients for live inference
- prompt generation commands
- chat or text generation workflow commands

This means the LLM foundation is present in the codebase, but the user-facing AI
runtime features are not complete yet.

## Configuration Storage

Configuration file location:

- Windows: `%APPDATA%/gasket/config.json`
- Linux and macOS: `~/.config/gasket/config.json`

## Development

Run tests:

```bash
pytest
pytest --cov=gasket --cov-report=term-missing
```

Run local checks:

```bash
ruff check src/
mypy src/
```

## Complete LLM Flow

The current LLM feature set is centered on configuration, validation, and mode
selection. A complete flow in the current codebase looks like this:

1. Run `gasket llm-mode` and choose one of the supported modes:
   - `local`
   - `api_provider`
   - `llm_api_key`
2. gasket persists `llm_mode` to `config.json` and resets the active mode to a
   valid default provider/model pair from the registry.
3. Use `gasket config list-models` to inspect the allowlisted models for the
   active provider.
4. Use `gasket config set-model <model>` to select a model. The command rejects
   any model that is not allowed for the active provider.
5. If the active mode is `llm_api_key`, optionally switch provider with
   `gasket config use-provider <name>` and store a credential with
   `gasket config set-key <provider> <api_key>`.
6. If the active mode is `api_provider`, optionally override the managed setup
   with `gasket config set-api-provider <name>` and
   `gasket config set-api-key <api_key>`.
7. Internal code can then call `resolve_llm()` to validate the active
   `(mode, provider, selected_model)` tuple before creating a concrete provider
   client.

Default mode-to-provider mapping today:

- `local` -> `ollama` -> `mistral`
- `api_provider` -> `cloudflare-default` -> `@cf/meta/llama-3.1-8b-instruct`
- `llm_api_key` -> `openai` -> `gpt-4o-mini`

Example BYOK flow:

```bash
gasket llm-mode
# choose: 3 (llm_api_key)

gasket config use-provider anthropic
gasket config set-key anthropic sk-ant-example
gasket config list-models anthropic
gasket config set-model claude-3-haiku-20240307
```

At this point the configuration layer is complete and internally resolvable.
What is not present yet is a public command such as `gasket generate` or
`gasket chat` that sends prompts to a live provider.

## License

MIT
