feat: interactive GitHub issues wizard (ralph-starter github)

[rubenmarcus]

Summary

• New ralph-starter github command — interactive wizard to browse repos, filter by label, multi-select issues, and start building
• New src/integrations/wizards/shared.ts — shared utilities (credential prompting, browse-or-URL choice) reused by upcoming Linear and Notion wizards
• ralph-starter run --from github (without --project/--issue) now redirects to the wizard instead of erroring
• Follows the same pattern as ralph-starter figma

Features

• Auth check: detects gh CLI auth or prompts for token (saves to ~/.ralph-starter/sources.json)
• Browse mode: lists repos → optional label filter → multi-select issues
• URL mode: paste a github.com URL (auto-detects repo + issue number)
• Options: --commit, --push, --pr, --validate, --agent, --max-iterations

Test plan

• ralph-starter github launches wizard
• ralph-starter run --from github (no flags) redirects to wizard
• ralph-starter run --from github --project owner/repo --issue 1 still works (no regression)
• Missing credentials prompts for token
• URL paste parses correctly
• pnpm build compiles (pre-existing type errors in visual-validation.ts are unrelated)

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[github-actions]

Issue Linking Reminder

This PR doesn't appear to have a linked issue. Consider linking to:

• This repo: Closes #123
• ralph-ideas: Closes multivmlabs/ralph-ideas#123

Using Closes, Fixes, or Resolves will auto-close the issue when this PR is merged.

---

If this PR doesn't need an issue, you can ignore this message.

[github-actions]

✔️ Bundle Size Analysis

Metric	Value
Base	2705.87 KB
PR	2705.87 KB
Diff	0 KB (0%)

Bundle breakdown

156K	dist/auth
80K	dist/automation
4.0K	dist/cli.d.ts
4.0K	dist/cli.d.ts.map
24K	dist/cli.js
16K	dist/cli.js.map
664K	dist/commands
28K	dist/config
4.0K	dist/index.d.ts
4.0K	dist/index.d.ts.map
4.0K	dist/index.js
4.0K	dist/index.js.map
916K	dist/integrations
100K	dist/llm
1.2M	dist/loop
188K	dist/mcp
60K	dist/presets
92K	dist/setup
40K	dist/skills
392K	dist/sources
76K	dist/ui
144K	dist/utils
336K	dist/wizard

[github-actions]

🔗 Docs Preview

Preview URL: https://feat-github-integration-wiza.ralph-starter-docs.pages.dev

This preview was deployed from the latest commit on this PR.

[greptile-apps]

Greptile Summary

This PR introduces a ralph-starter github interactive wizard command that guides users through authenticating with GitHub, browsing repositories and labels, multi-selecting issues, and delegating each issue to the existing runCommand loop. It also adds a shared src/integrations/wizards/shared.ts utility module designed to be reused by upcoming Linear and Notion wizards, and adds a fallback in run.ts so that ralph-starter run --from github (without --project/--issue) redirects to the wizard instead of erroring.

Key findings:

• TypeScript convention violation: All new data-structure declarations (GitHubWizardOptions, GitHubRepo, GitHubIssue, GitHubLabel, CredentialOptions) use interface instead of the project's default type keyword for DTOs and simple data structures.
• Browse mode / token-only auth gap: ensureCredentials can succeed via a plain token (env var or config file) without gh CLI, but browse mode unconditionally shells out to gh repo list / gh issue list. Users who authenticate via token but have no gh CLI installed will see a misleading failure. Only URL mode works reliably in that setup.
• Circular dependency: run.ts imports githubCommand from github.ts, while github.ts already imports runCommand from run.ts. This cycle works at runtime because both exports are functions, but it is a code smell and could cause problems with bundlers or future refactoring.
• Undocumented commands in README: The new README entries for ralph-starter linear and ralph-starter notion reference commands that are not yet implemented in this PR.

The core wizard flow is sound and the fallback in run.ts is well-placed. However, the style violations, circular import, browse-mode auth gap, and unimplemented command documentation should be addressed.

Confidence Score: 3/5

• Mergeable with minor concerns — no crash-level bugs, but circular dependency, token-only browse failure, style violations, and unimplemented command documentation should be addressed.
• The core wizard flow is sound and the fallback in run.ts is well-placed. However, there are four concrete issues: (1) TypeScript style violations using interface instead of type for all new DTOs/simple data structures, violating project conventions; (2) a circular import between run.ts and github.ts that works at runtime but is a code smell; (3) a UX gap where browse mode fails for users with a plain token but no gh CLI; and (4) documentation of commands (linear, notion) that don't exist yet, which will confuse users.
• src/commands/github.ts (style violations and auth gap), src/integrations/wizards/shared.ts (style violation), src/commands/run.ts (circular dependency), README.md (unimplemented commands).

Sequence Diagram

sequenceDiagram
    actor User
    participant CLI as cli.ts
    participant GH as github.ts (githubCommand)
    participant Shared as shared.ts
    participant GhCLI as gh CLI
    participant Run as run.ts (runCommand)

    User->>CLI: ralph-starter github [options]
    CLI->>GH: githubCommand(options)

    GH->>Shared: ensureCredentials('github', ...)
    Shared->>GhCLI: gh auth status
    alt gh CLI authenticated
        GhCLI-->>Shared: ok → '__cli_auth__'
    else no gh CLI / not authed
        Shared->>Shared: check env var / sources.json
        alt no token found
            Shared->>User: prompt for token (masked)
            User-->>Shared: token
            Shared->>Shared: setSourceCredential → sources.json
        end
    end
    Shared-->>GH: credential

    GH->>Shared: askBrowseOrUrl('GitHub')
    Shared-->>GH: 'browse' | 'url'

    alt URL mode
        GH->>Shared: askForUrl('GitHub', /github\.com/)
        Shared-->>GH: url string
        GH->>GH: parseGitHubUrl(url)
        GH->>Run: runCommand(undefined, {from:'github', project, issue, ...})
    else Browse mode
        GH->>GhCLI: gh repo list --json
        GhCLI-->>GH: repos[]
        GH->>User: select a repository
        GH->>GhCLI: gh label list -R owner/repo
        GhCLI-->>GH: labels[]
        GH->>User: (optional) filter by label
        GH->>GhCLI: gh issue list -R owner/repo [--label x]
        GhCLI-->>GH: issues[]
        GH->>User: checkbox multi-select issues
        loop for each selected issue
            GH->>Run: runCommand(undefined, {from:'github', project, issue, ...})
        end
    end

    alt run.ts --from github (no --project/--issue)
        Run->>GH: githubCommand(options) [wizard fallback]
    end

Loading

_{Last reviewed commit: b3e759b}

[github-actions]

This PR has been automatically marked as stale because it has not had recent activity.
It will be closed in 7 days if no further activity occurs.
Please update or comment if this PR is still in progress.