Auto-create missing GitHub labels when creating issues

[helixclaw]

Summary

When iloom creates issues (e.g., epic issues via il plan), it passes labels to gh issue create --label. If the label doesn't exist on the repository, the gh CLI fails with an error. iloom should automatically check for and create missing labels before attempting to create the issue.

Problem

Currently, createIssue() in src/utils/github.ts passes labels directly to the gh CLI without verifying they exist. This causes failures when:

• A user runs il plan on a fresh repo that doesn't have the epic label
• Any issue creation specifies a label that hasn't been manually created on the repo

This is a self-demonstrating bug — creating this very epic with an epic label fails if the label doesn't exist.

Proposed Solution

Add an ensureLabelsExist() utility function in src/utils/github.ts that:

1. Checks if each label exists on the repo using gh api to query the labels endpoint
2. Creates any missing labels using gh api POST to the labels endpoint
3. Is called by createIssue() before the gh issue create command

This should be a general-purpose solution that works for any label, not just epic.

Key Files

• src/utils/github.ts — createIssue() function (line ~247)
• src/mcp/GitHubIssueManagementProvider.ts — calls createIssue()
• src/utils/github.test.ts — tests for github utilities

Acceptance Criteria

• Missing labels are auto-created before issue creation
• Existing labels are not duplicated or modified
• Error from label creation is handled gracefully (e.g., permission denied — should warn and continue without label rather than failing)
• Works with the optional repo parameter for cross-repo operations
• Tests cover: label exists, label missing and created, label creation fails gracefully

[helixclaw]

Architectural Decision Record

Design Rationale

The gh issue create --label command fails hard if a label doesn't exist on the repo. Rather than requiring users to manually create labels beforehand, iloom should handle this transparently.

Key Decisions

1. General-purpose solution: ensureLabelsExist() works for any label, not just epic. This benefits all issue creation paths in iloom.

2. Graceful degradation over hard failure: If a label can't be created (e.g., permission denied on a repo you don't own), the function warns and continues without that label. Issue creation should never fail just because a label couldn't be applied.

3. Return filtered list pattern: ensureLabelsExist(labels, repo) returns only the labels that exist or were successfully created. The caller uses this filtered list instead of the original.

4. GitHub API for checking: Use gh api repos/{owner}/{repo}/labels/{name} rather than gh label list to check individual labels. This is more efficient (one API call per label vs listing all labels).

5. Default color for auto-created labels: Use ededed (light gray) as the default color for auto-created labels. Users can customize the color later in GitHub's UI.

Trade-offs

• Extra API calls: Each label requires a check (and potentially a create) API call before issue creation. For typical usage (1-2 labels), this adds ~1-2 seconds. Acceptable tradeoff for reliability.
• No caching: Labels are checked every time. A per-session cache could optimize this, but adds complexity for minimal gain since createIssue is typically called a handful of times per session.

Child Issues Created

Issue	Title	Dependencies
#14	Add ensureLabelsExist() utility function to github.ts	None
#15	Integrate ensureLabelsExist() into createIssue() flow	#14

Dependency Graph

graph TD
    14["Add ensureLabelsExist() utility"]
    15["Integrate into createIssue() flow"]
    14 --> 15
    click 14 "https://github.com/NoahCardoza/iloom-cli/issues/14"
    click 15 "https://github.com/NoahCardoza/iloom-cli/issues/15"

Loading

Recommended Execution Order

1. Start with Add ensureLabelsExist() utility function to github.ts #14 — implement the ensureLabelsExist() utility function with tests
2. Then Integrate ensureLabelsExist() into createIssue() flow #15 — integrate into the createIssue() flow and add integration tests