Iloom init command should detect when no remotes are set up and offer to help set them up (as long as gh CLI is up and running)

[no-perms-just-frizz]

Draft PR for issue #361

This PR was created automatically by iloom.

[acreeger]

Bug Report / Enhancement Analysis

Questions for Reporter

Question	Answer
Should this check happen during il init only, or also at the start of il start as a runtime check?	Both commands - il start should trigger il init (like first-time setup) and il init should help configure remotes
When no remotes exist, should we offer to set up GitHub remote specifically, or also support other Git hosts (GitLab, Bitbucket)?	GitHub only (uses gh CLI)
If the user is in a repository that is already cloned from GitHub but has no remotes (edge case: removed remotes manually), should we detect the original GitHub URL from gh CLI or require re-adding?	Ask user for the git URL - don't try to auto-detect from gh CLI
Should this be a hard failure (blocking) or a warning with option to continue without remote setup?	il start should run il init (like first-time setup) and il init should help configure remotes

Problem Summary
The il start command fails when a repository has no Git remotes configured, but iloom does not detect this condition or guide users to fix it.

User Impact
New users setting up iloom on a fresh repository cannot proceed with il start and receive unhelpful error messages. This creates a poor onboarding experience.

Actual Behavior
il start fails with an error when Git remotes are not configured, leaving users stuck without guidance on how to fix the issue.

Expected Behavior

1. il init should detect missing Git remotes and offer to help configure them (GitHub-only, prompt user for URL)
2. il start should detect missing remotes and trigger il init flow (similar to first-time setup) to guide the user through configuration

Next Steps

• Technical analysis to identify where remote checks should be added
• Implementation planning and execution

---

📋 Complete Context & Details (click to expand)

Context from Documentation

The README.md shows that gh auth login is step 2 of the Quick Start, indicating that:

• GitHub CLI is a required dependency
• iloom expects GitHub integration to be available
• Users are expected to have GitHub authentication set up

The CLAUDE.md architecture shows:

• GitHubService.ts handles GitHub CLI integration
• GitWorktreeManager.ts manages Git operations
• Commands like il start orchestrate these services

Additional Context

When This Occurs:

• Fresh repository initialization (git init without adding remote)
• Cloned repository where remotes were manually removed
• Repository migrated from another Git host

Dependencies Already Available:

• GitHub CLI (gh) is required per README.md
• The gh CLI can help configure remotes via gh repo set-default or similar commands

Related Workflows:

• il init: Configuration wizard (logical place to check/fix remotes)
• il start: Creates workspace (needs remote for issue tracking integration)

Design Decisions (from reporter):

1. Check remotes in BOTH il init and il start commands
2. GitHub-only support (leverages existing gh CLI dependency)
3. il start should trigger il init flow when remotes are missing
4. Prompt user for GitHub URL rather than auto-detecting

[acreeger]

Complexity Assessment

Classification: SIMPLE

Metrics:

• Estimated files affected: 5
• Estimated lines of code: ~180
• Breaking changes: No
• Database migrations: No
• Cross-cutting changes: No
• File architecture quality: Good
• Overall risk level: Low

Reasoning: This feature requires adding remote detection logic to two existing commands (init.ts and start.ts), a small utility function in remote.ts, and updating the init-prompt.txt template to guide users through remote setup in the init wizard. The init command already has infrastructure for detecting and displaying remotes (lines 343-382), so we're reusing existing patterns. Start command simply needs to call init when remotes are missing. No changes to core architectural layers or cross-cutting concerns.

Files to modify:

1. src/commands/init.ts - Add remote detection and prompt for GitHub URL
2. src/commands/start.ts - Check for remotes and trigger init flow if missing
3. src/lib/remote.ts (or similar utility) - Add utility function for remote detection
4. init-prompt.txt - Update init wizard template to include remote setup guidance
5. Tests for the above changes

[acreeger]

Combined Analysis & Plan - Issue #361

Executive Summary

Issue #361 reports that il start fails when no Git remotes are configured, without providing guidance to fix it. The solution involves: (1) adding a hasNoRemotes() utility function, (2) updating start.ts to detect missing remotes and trigger the init flow, and (3) extending the init-prompt template to guide users through adding a GitHub remote via git remote add.

Questions and Key Decisions (if applicable)

Question	Answer
Should this check happen during il init only, or also at il start?	Both - il start triggers il init when remotes missing (confirmed by user)
Support other Git hosts (GitLab, Bitbucket)?	GitHub only - uses gh CLI (confirmed by user)
Auto-detect GitHub URL or prompt user?	Prompt user for GitHub URL (confirmed by user)

Implementation Overview

High-Level Execution Phases

1. Add hasNoRemotes() utility: Create function in src/utils/remote.ts following existing hasMultipleRemotes() pattern
2. Update start.ts: Add check after first-run setup that triggers launchFirstRunSetup() with custom message when no remotes detected
3. Extend init-prompt.txt: Expand NO_REMOTES block to prompt user for GitHub URL and execute git remote add origin <url>
4. Add tests: Unit tests for new utility function and integration behavior

Quick Stats

• 3 files to modify
• 0 new files to create
• 0 files to delete
• Dependencies: None

---

Complete Analysis & Implementation Details (click to expand)

Research Findings

Problem Space

• Problem: Users with no Git remotes configured cannot use il start and receive unhelpful error messages
• Architectural context: init.ts already detects remotes at lines 343-382 and passes NO_REMOTES variable to template; template only shows warning, doesn't help add remotes
• Edge cases: Fresh git init repos, repos with remotes manually removed

Codebase Research

• Entry point: src/commands/init.ts:343-382 - Remote detection already exists
• Dependencies: parseGitRemotes() in src/utils/remote.ts:19-54 - Parses git remote -v output
• Similar patterns: hasMultipleRemotes() in src/utils/remote.ts:82-96 - Exact pattern for hasNoRemotes()
• Template: templates/prompts/init-prompt.txt:313-315 - NO_REMOTES block only warns, doesn't help add remotes
• Start command first-run check: src/commands/start.ts:119-128 - Existing pattern for triggering init flow

Affected Files

• /src/utils/remote.ts:82-96 - Add hasNoRemotes() function after hasMultipleRemotes()
• /src/commands/start.ts:119-137 - Add remote check after first-run setup
• /templates/prompts/init-prompt.txt:313-315 - Extend NO_REMOTES handling to add remote

Integration Points

• start.ts imports hasMultipleRemotes from remote.ts (line 18) - will also import hasNoRemotes
• start.ts imports launchFirstRunSetup from first-run-setup.ts (line 21) - will use for triggering init
• init.ts already passes NO_REMOTES variable to template (line 405)

---

Implementation Plan

Automated Test Cases to Create

Test File: /src/utils/remote.test.ts (MODIFY)

describe('hasNoRemotes', () => {
  it('should return true when no remotes exist', async () => {
    // mock execa to return empty stdout
  })
  
  it('should return false when remotes exist', async () => {
    // mock execa to return remote output
  })
  
  it('should return false when git command fails', async () => {
    // mock execa to reject - same behavior as hasMultipleRemotes
  })
})

Files to Modify

1. /src/utils/remote.ts:82-96

Change: Add hasNoRemotes() function following the exact pattern of hasMultipleRemotes()

// Add after hasMultipleRemotes() at line 96
/**
 * Check if repository has no remotes
 */
export async function hasNoRemotes(cwd?: string): Promise<boolean> {
  try {
    const remotes = await parseGitRemotes(cwd)
    return remotes.length === 0
  } catch (error) {
    // Same error handling pattern as hasMultipleRemotes
    const errMsg = error instanceof Error ? error.message : String(error)
    if (/not a git repository/i.test(errMsg)) {
      logger.debug('Skipping git remote check: not a git repository')
    } else {
      logger.warn(`Unable to check git remotes: ${errMsg}`)
    }
    return false
  }
}

2. /src/commands/start.ts:119-137

Change: Add remote check after first-run setup that triggers init when no remotes detected

Location: After line 128 (after the existing first-run setup check), before the repo lookup at line 130

// After line 128, before "let repo: string | undefined"
// Check for missing remotes and trigger init flow if needed
if (!isJsonMode && (await hasNoRemotes())) {
  getLogger().warn('No git remotes detected. iloom requires a GitHub remote to function.')
  await launchFirstRunSetup('Help me configure a GitHub remote for this repository. There are no git remotes configured.')
  // Continue after setup - remotes should now be configured
}

Also add import at line 18: import { getConfiguredRepoFromSettings, hasMultipleRemotes, hasNoRemotes } from '../utils/remote.js'

3. /templates/prompts/init-prompt.txt:313-315

Change: Extend NO_REMOTES handling to prompt for GitHub URL and execute git remote add

Replace lines 313-315:

{{#IF NO_REMOTES}}
**Warning:** No git remotes detected. The user will need to configure a remote before using iloom's GitHub features.
{{/IF NO_REMOTES}}

With expanded block:

{{#IF NO_REMOTES}}
**CRITICAL: No git remotes detected.** This repository has no Git remotes configured. iloom requires a GitHub remote to function properly.

**Before proceeding with other configuration, you MUST help the user set up a remote:**

1. **Ask for the GitHub repository URL:**
   - Question: "Please provide your GitHub repository URL (e.g., https://github.com/owner/repo or [email protected]:owner/repo)"
   - Validate the URL matches GitHub format (HTTPS or SSH)

2. **Add the remote using git:**
   ```bash
   git remote add origin <user-provided-url>

3. Verify the remote was added:

   git remote -v

4. Inform the user: "Remote 'origin' has been configured. You can now proceed with iloom configuration."

Important: If the user doesn't have a GitHub repository yet, guide them to:

• Create one at https://github.com/new
• Then return to provide the URL

After configuring the remote, proceed to Phase 1 (Local Development Settings).
{{/IF NO_REMOTES}}

### Detailed Execution Order

#### Phase 1: Add hasNoRemotes() utility
1. Add `hasNoRemotes()` function to `/src/utils/remote.ts` after `hasMultipleRemotes()` at line 96 -> Verify: Function exported and follows same pattern
2. Add unit tests to `/src/utils/remote.test.ts` -> Verify: Tests pass

#### Phase 2: Update start.ts
1. Add `hasNoRemotes` to import at line 18 -> Verify: Import compiles
2. Add remote check after line 128 (after first-run setup block) -> Verify: Check triggers init flow when no remotes

#### Phase 3: Update init-prompt.txt
1. Replace lines 313-315 with expanded NO_REMOTES handling -> Verify: Template contains new guidance

#### Phase 4: Build and test
1. Run `pnpm build` -> Verify: TypeScript compiles successfully
2. Run `pnpm test` -> Verify: All tests pass including new remote.test.ts tests

### Dependencies and Configuration

None

</details>

[acreeger]

Implementation Complete - Issue #361

Summary

Implemented remote detection feature that checks for missing Git remotes during il start and triggers the init flow to help users configure a GitHub remote. This addresses the issue where users with no remotes configured received unhelpful error messages.

Changes Made

• src/utils/remote.ts: Added hasNoRemotes() utility function
• src/utils/remote.test.ts: Added 3 unit tests for hasNoRemotes()
• src/commands/start.ts: Added remote check after first-run setup that triggers init flow
• src/utils/first-run-setup.ts: Extended launchFirstRunSetup() to accept optional custom message
• src/commands/start.test.ts: Added hasNoRemotes to mock exports
• templates/prompts/init-prompt.txt: Extended NO_REMOTES handling with step-by-step guidance for adding GitHub remote

Validation Results

• Tests: 89 passed (remote.test.ts + start.test.ts)
• Typecheck: Passed
• Lint: Passed
• Build: Passed

---

Detailed Changes by File (click to expand)

Files Modified

/src/utils/remote.ts

Changes: Added hasNoRemotes() function after hasMultipleRemotes() following same pattern

• Returns true when parseGitRemotes() returns empty array
• Same error handling as hasMultipleRemotes() (returns false on errors)

/src/utils/remote.test.ts

Changes: Added hasNoRemotes import and 3 test cases

• Tests true when no remotes exist (empty stdout)
• Tests false when remotes exist
• Tests false when git command fails

/src/commands/start.ts

Changes: Added import and remote check in execute method

• Added hasNoRemotes to import from ../utils/remote.js
• Added check after first-run setup (line 130-135) that triggers init flow with custom message when no remotes detected

/src/utils/first-run-setup.ts

Changes: Extended launchFirstRunSetup to accept optional custom message parameter

• Added customMessage?: string parameter
• Uses default message if no custom message provided

/src/commands/start.test.ts

Changes: Added hasNoRemotes mock to remote utilities mock

/templates/prompts/init-prompt.txt

Changes: Replaced simple NO_REMOTES warning with comprehensive guidance

• Added step-by-step instructions for adding GitHub remote
• Includes URL format examples (HTTPS and SSH)
• Guides users to create GitHub repo if needed
• Instructs to proceed to Phase 1 after remote is configured

Test Coverage Added

• src/utils/remote.test.ts: 3 tests for hasNoRemotes() behavior

Dependencies Added

None