npm-cli-gh-issue-preparator

Welcome to npm-cli-gh-issue-preparator, this tool helps you to prepare you task by AI.

Usage 🛠️

Here's how you can use npm-cli-gh-issue-preparator:

Usage: npm-cli-gh-issue-preparator [options] [command]

CLI tool to prepare GitHub issues

Options:
  -h, --help                                display help for command

Commands:
  startDaemon [options]                     Start daemon to prepare GitHub issues
  notifyFinishedIssuePreparation [options]  Notify that issue preparation is finished
  help [command]                            display help for command

Configuration

Parameters are resolved using a 3-tier priority system (highest to lowest):

1. GitHub Project README (highest priority) -- YAML extracted from <details><summary>config</summary> section
2. CLI arguments -- passed via command line options
3. Config YAML file (lowest priority) -- base configuration loaded via --configFilePath

All parameters can be specified in a YAML config file. See config.example.yml for a complete example.

GitHub Project README Config

The GitHub Project README can contain a collapsible <details> section with YAML configuration that overrides both CLI arguments and config file values:

<details>
<summary>config</summary>

maximumPreparingIssuesCount: 2
utilizationPercentageThreshold: 99
defaultAgentName: 'custom-agent'
thresholdForAutoReject: 3
</details>

Only the content inside the <details><summary>config</summary> section is parsed as YAML. Other content in the README is ignored. projectUrl and configFilePath cannot be set via Project README since the README is fetched using these values.

Parameters

• thresholdForAutoReject (default: 3) - Number of consecutive auto-rejection comments before automatically escalating the issue to the awaiting quality check status. Can be set via CLI argument --thresholdForAutoReject, config file, or GitHub Project README config.
• logFileDirPath (optional) - Directory for per-invocation log files. The wrapper script reads this from the YAML config file and creates log files at <dir>/<org>_<repo>_<issueNumber>_<YYYYMMDD_HHMMSS>.log. Must be set in the config file (cannot be set via GitHub Project README config, as the wrapper reads the YAML file directly).

Wrapper Script Contract

startDaemon invokes a wrapper script (aw) for each issue. The wrapper receives --configFilePath <path> as the single source of truth for project-scoped values. The wrapper is expected to call notifyFinishedIssuePreparation --configFilePath <path> --issueUrl <url>.

projectUrl MUST be present in the config YAML file when using startDaemon. The wrapper script reads projectUrl directly from the config file; providing it only via --projectUrl CLI flag is not sufficient and will cause startDaemon to fail with an error.

awaitingWorkspaceStatus, preparationStatus, and awaitingQualityCheckStatus can be provided in the config YAML or in the GitHub Project README (since the wrapper can fetch the README using projectUrl from the config file). projectUrl and configFilePath cannot be set via Project README since the README is fetched using these values.

Issue Labels

You can use GitHub issue labels to customize the agent and model selection for individual issues:

• llm-agent:{agent-name} - Overrides the default LLM agent for this issue
• llm-model:{model-name} - Overrides the default LLM model for this issue

Example: llm-agent:custom-impl, llm-model:claude-sonnet-4-6

Label priority for agent selection:

1. llm-agent: label (highest priority)
2. category: label (for backward compatibility)
3. defaultLlmAgentName parameter
4. defaultAgentName parameter (lowest priority)

Model selection:

1. llm-model: label (highest priority)
2. defaultLlmModelName parameter (lowest priority)

If neither is configured for an issue, the use case throws an error. A model must always be provided via --defaultLlmModelName or an llm-model: label.

Note: The category: label serves an additional role beyond agent selection: in notifyFinishedIssuePreparation, issues with a non-e2e category: label skip the PR check. Issues using only llm-agent: for agent selection still require a category: label (other than category:e2e) to skip the PR check during notification.

Example 📖

Here's a quick example to illustrate its usage:

Using config file

npx npm-cli-gh-issue-preparator startDaemon --configFilePath ./config.yml

Start preparation (with CLI overrides)

npx npm-cli-gh-issue-preparator startDaemon --configFilePath ./config.yml --projectUrl <projectUrl> --awaitingWorkspaceStatus "Awaiting workspace" --preparationStatus "Preparation" --defaultAgentName "impl" --defaultLlmModelName "claude-opus" --defaultLlmAgentName "impl"

Notify finished issue preparation

npx npm-cli-gh-issue-preparator notifyFinishedIssuePreparation --configFilePath ./config.yml --issueUrl <issueUrl>

Notify finished issue preparation with webhook notification

npx npm-cli-gh-issue-preparator notifyFinishedIssuePreparation --configFilePath ./config.yml --issueUrl <issueUrl> --workflowBlockerResolvedWebhookUrl 'https://example.com/webhook?url={URL}&message={MESSAGE}'

When a workflow blocker issue's status changes to awaiting quality check, a GET request is sent to the specified webhook URL. The {URL} and {MESSAGE} placeholders are replaced with URL-encoded values.

Contributing

See CONTRIBUTING.md

License

MIT