Merge pull request #6 from Oltrematica/004-github-repo-selection

004 GitHub repo selection

Author: amargiovanni

CLAUDE.md

@@ -6,6 +6,8 @@ Auto-generated from all feature plans. Last updated: 2025-11-28
 - Python 3.9+ (per constitution, leveraging type hints) + Standard library (urllib, json, csv, os, re); optional: requests (002-jira-integration)
 - CSV files for export (same as existing GitHub exports) (002-jira-integration)
 - Python 3.9+ (per constitution, leveraging type hints) + Standard library only (urllib, json, csv, os, re, datetime, statistics); optional: requests (already used in jira_client.py) (003-jira-quality-metrics)
+- Python 3.9+ (as per constitution, leveraging type hints) + Standard library only (urllib, json); optional: requests (existing pattern) (004-github-repo-selection)
+- N/A (repos.txt file is input, not storage) (004-github-repo-selection)
 
 - Python 3.9+ (as per constitution, leveraging type hints) + Standard library only (urllib, json, csv, os, re); optional: requests (001-modular-refactor)
 
@@ -37,10 +39,10 @@ python github_analyzer.py --days 7
 Python 3.9+ (as per constitution, leveraging type hints): Follow standard conventions
 
 ## Recent Changes
+- 004-github-repo-selection: Added Python 3.9+ (as per constitution, leveraging type hints) + Standard library only (urllib, json); optional: requests (existing pattern)
 - 003-jira-quality-metrics: Added Python 3.9+ (per constitution, leveraging type hints) + Standard library only (urllib, json, csv, os, re, datetime, statistics); optional: requests (already used in jira_client.py)
 - 002-jira-integration: Added Python 3.9+ (per constitution, leveraging type hints) + Standard library (urllib, json, csv, os, re); optional: requests
 
-- 001-modular-refactor: Added Python 3.9+ (as per constitution, leveraging type hints) + Standard library only (urllib, json, csv, os, re); optional: requests
 
 <!-- MANUAL ADDITIONS START -->
 <!-- MANUAL ADDITIONS END -->

specs/004-github-repo-selection/checklists/comprehensive.md

@@ -0,0 +1,148 @@
+# Requirements Quality Checklist: GitHub Repository Interactive Selection
+
+**Purpose**: Validate specification completeness, clarity, and consistency before implementation
+**Created**: 2025-11-29
+**Feature**: [spec.md](../spec.md)
+**Focus**: Comprehensive (UX, API, Validation, Non-interactive)
+**Depth**: Standard (PR review gate)
+
+---
+
+## Requirement Completeness
+
+- [x] CHK001 - Are all five menu options [A/S/O/L/Q] explicitly defined with their behavior? [Completeness, Spec §FR-002] ✓ Defined in FR-002 and Display Format section
+- [x] CHK002 - Are requirements for repos.txt file loading specified (path, format, empty handling)? [Completeness, Spec §US1] ✓ US1-AC1,2,3 cover all cases
+- [x] CHK003 - Are pagination requirements defined for both user repos AND org repos? [Completeness, Spec §FR-007] ✓ FR-007 covers both explicitly
+- [x] CHK004 - Are requirements specified for displaying repository descriptions in the list? [Completeness, Display Format] ✓ Added Display Format section with truncation
+- [x] CHK005 - Are requirements for private repository visibility indicator defined? [Completeness, Display Format] ✓ Added [private] marker in Display Format
+- [x] CHK006 - Are error message content requirements specified (what text to show for each error type)? [Completeness, Edge Cases] ✓ Added specific error messages to all edge cases
+- [x] CHK007 - Are requirements defined for the "retry or quit" flow after org not found? [Completeness, Spec §Edge Cases] ✓ "allow retry or quit" specified
+
+---
+
+## Requirement Clarity
+
+- [x] CHK008 - Is "personal repos" clarified with specific affiliation values (owner,collaborator)? [Clarity, Spec §Clarifications] ✓ Clarified in Session 2025-11-29
+- [x] CHK009 - Is the exact menu prompt text specified or left to implementation? [Clarity, Display Format] ✓ Added Menu Prompt Format section with exact text
+- [x] CHK010 - Are the performance thresholds "under 10 seconds" and "under 15 seconds" clearly scoped? [Clarity, Spec §SC-002, SC-003] ✓ Scoped to specific repo counts and network conditions
+- [x] CHK011 - Is "clear error message" quantified with specific content requirements? [Clarity, Edge Cases] ✓ All error messages now have exact text
+- [x] CHK012 - Is "graceful exit" defined with specific behavior and message? [Clarity, Edge Cases] ✓ "GitHub analysis skipped." message specified
+- [x] CHK013 - Are the exact validation patterns for repo format documented? [Clarity, Validation Patterns] ✓ Added Validation Patterns section with regex
+- [x] CHK014 - Are the exact validation patterns for org name documented? [Clarity, Validation Patterns] ✓ Added with pattern and examples
+
+---
+
+## Requirement Consistency
+
+- [x] CHK015 - Are menu options consistent between spec (A/S/O/L/Q) and quickstart examples? [Consistency] ✓ All use [A/S/O/L/Q]
+- [x] CHK016 - Is the selection format "1,3,5" or "1-3" consistent with existing parse_project_selection()? [Consistency, Spec §FR-010] ✓ Same format documented
+- [x] CHK017 - Are EOF/KeyboardInterrupt handling requirements consistent across all menu states? [Consistency, Spec §FR-004] ✓ FR-004 applies universally
+- [x] CHK018 - Are error handling patterns consistent between list_user_repos and list_org_repos? [Consistency, contracts/internal-api.md] ✓ Same RateLimitError/APIError patterns
+- [x] CHK019 - Is the "owner/repo" format requirement consistent across manual entry and API responses? [Consistency, Spec §FR-009, FR-011] ✓ full_name format used consistently
+
+---
+
+## Jira Pattern Consistency (FR-003)
+
+- [x] CHK020 - Does the menu structure match select_jira_projects pattern (options display, prompt format)? [Consistency, Spec §FR-003] ✓ Same pattern documented in Display Format
+- [x] CHK021 - Is the list numbering format consistent with Jira project list display? [Consistency, Spec §FR-003] ✓ Same "N. name - description" format
+- [x] CHK022 - Is the selection input parsing reusing or mirroring parse_project_selection()? [Consistency, research.md §5] ✓ Documented in research.md decision
+- [x] CHK023 - Is the "invalid choice retry" behavior consistent with Jira selection flow? [Consistency, Spec §FR-003] ✓ Same retry pattern per FR-003
+- [x] CHK024 - Are logging patterns (output.log) consistent with select_jira_projects implementation? [Consistency] ✓ Uses TerminalOutput per contracts
+
+---
+
+## Acceptance Criteria Quality
+
+- [x] CHK025 - Can SC-001 "within 30 seconds" be objectively measured? [Measurability, Spec §SC-001] ✓ Split into menu (2s) and listing (30s) with clear scope
+- [x] CHK026 - Can SC-004 "no regression" be verified with specific test criteria? [Measurability, Spec §SC-004] ✓ Testable: repos.txt loading unchanged
+- [x] CHK027 - Can SC-005 "UX mirrors Jira" be verified with specific comparison points? [Measurability, Spec §SC-005] ✓ Menu format, prompts, error handling defined
+- [x] CHK028 - Are acceptance scenarios in US1-US4 testable without implementation details? [Measurability] ✓ All scenarios use Given/When/Then format
+- [x] CHK029 - Is "all repositories are shown" in US2-AC3 measurable (what if 1000+ repos)? [Clarity, Edge Cases] ✓ Partial response edge case added for large lists
+
+---
+
+## Scenario Coverage
+
+### Primary Flow Coverage
+- [x] CHK030 - Are requirements complete for [A] all personal repos flow? [Coverage, Spec §US2] ✓ US2-AC1
+- [x] CHK031 - Are requirements complete for [S] manual specification flow? [Coverage, Spec §US4] ✓ US4 complete
+- [x] CHK032 - Are requirements complete for [O] organization repos flow? [Coverage, Spec §US3] ✓ US3 complete
+- [x] CHK033 - Are requirements complete for [L] select from list flow? [Coverage, Spec §US2] ✓ US2-AC2,3,4
+- [x] CHK034 - Are requirements complete for [Q] quit/skip flow? [Coverage, Spec §FR-002] ✓ FR-004 covers exit behavior
+
+### Alternate Flow Coverage
+- [x] CHK035 - Are requirements defined for re-prompting after invalid menu choice? [Coverage, FR-003] ✓ Jira pattern includes retry
+- [x] CHK036 - Are requirements defined for re-prompting after empty manual input? [Coverage, Spec §US4-AC3] ✓ "can correct or continue"
+- [x] CHK037 - Are requirements defined for selecting "all" in list mode? [Coverage, Validation Patterns] ✓ "all" documented as valid input
+
+### Exception Flow Coverage
+- [x] CHK038 - Are requirements defined for API authentication failure? [Coverage, Edge Cases] ✓ Added with specific error message
+- [x] CHK039 - Are requirements defined for network timeout during repo listing? [Coverage, Edge Cases] ✓ Added with retry option
+- [x] CHK040 - Are requirements defined for partial API response (some repos fetched, then error)? [Coverage, Edge Cases] ✓ Added graceful degradation
+
+---
+
+## Edge Case Coverage
+
+- [x] CHK041 - Are requirements defined for user with zero repositories? [Edge Case, Edge Cases] ✓ Added with specific message
+- [x] CHK042 - Are requirements defined for organization with zero repositories? [Edge Case, Edge Cases] ✓ Added with retry option
+- [x] CHK043 - Are rate limit wait time display requirements specified? [Edge Case, Spec §Edge Cases] ✓ "Waiting X seconds..." format
+- [x] CHK044 - Are requirements for "special characters in org name" clearly defined? [Edge Case, Validation Patterns] ✓ Regex pattern with examples
+- [x] CHK045 - Are requirements defined for repos.txt with invalid entries mixed with valid? [Edge Case, US1-AC3] ✓ Similar to US4-AC4
+- [x] CHK046 - Are requirements defined for selection numbers exceeding list length? [Edge Case, Edge Cases] ✓ Added ignore with warning
+
+---
+
+## Non-Functional Requirements
+
+### Performance
+- [x] CHK047 - Are performance requirements scoped to specific network conditions? [Clarity, NFR §Performance] ✓ Added "< 200ms latency" assumption
+- [x] CHK048 - Are timeout values for API calls specified? [Coverage, NFR §Assumptions] ✓ Uses GitHubClient default 30s
+
+### Security
+- [x] CHK049 - Are token exposure prevention requirements documented? [Coverage, NFR §Security] ✓ Added Security section
+- [x] CHK050 - Is input validation for org name protecting against injection? [Coverage, NFR §Security] ✓ Regex validation + safe URL construction
+
+### Accessibility
+- [x] CHK051 - Are requirements defined for screen reader compatibility of menu output? [Coverage, NFR §Accessibility] ✓ Added Accessibility section
+- [x] CHK052 - Are requirements defined for non-ANSI terminal support? [Coverage, NFR §Accessibility] ✓ Plain text, optional formatting
+
+---
+
+## Dependencies & Assumptions
+
+- [x] CHK053 - Is the GitHub token scope requirement ("repo") documented as assumption? [Assumption, Spec §Assumptions] ✓ First assumption listed
+- [x] CHK054 - Is the assumption "user knows org names" validated or alternatives considered? [Assumption, Spec §Assumptions] ✓ Documented as design decision
+- [x] CHK055 - Are dependencies on existing GitHubClient methods documented? [Dependency, plan.md] ✓ paginate(), rate limit handling
+- [x] CHK056 - Is the dependency on TerminalOutput documented? [Dependency, contracts/internal-api.md] ✓ In function signature
+
+---
+
+## Ambiguities & Conflicts
+
+- [x] CHK057 - Is there ambiguity between "skip" (FR-014) and "error message" (US1-AC4) for non-interactive mode? [Resolved] ✓ US1-AC4 updated to "informational log message"
+- [x] CHK058 - Is there conflict between "all repos shown" (US2-AC3) and potential max_pages limit? [Resolved, Edge Cases] ✓ Partial response edge case added
+- [x] CHK059 - Is the term "valid repositories" in US1-AC3 defined (format valid? exists on GitHub? accessible?)? [Clarity] ✓ Format validation per FR-011
+- [x] CHK060 - Is the behavior for [O] option after seeing org list (select vs all) fully specified? [Clarity, US3-AC5] ✓ "choose [A] after seeing the list"
+
+---
+
+## Summary
+
+| Category | Items | Status |
+|----------|-------|--------|
+| Completeness | 7 | ✅ All resolved |
+| Clarity | 7 | ✅ All resolved |
+| Consistency | 5 | ✅ All resolved |
+| Jira Pattern | 5 | ✅ All resolved |
+| Acceptance Criteria | 5 | ✅ All resolved |
+| Scenario Coverage | 11 | ✅ All resolved |
+| Edge Cases | 6 | ✅ All resolved |
+| Non-Functional | 6 | ✅ All resolved |
+| Dependencies | 4 | ✅ All resolved |
+| Ambiguities | 4 | ✅ All resolved |
+
+**Total Items**: 60
+**Completed**: 60
+**Status**: ✅ PASS

specs/004-github-repo-selection/checklists/requirements.md

@@ -0,0 +1,37 @@
+# Specification Quality Checklist: GitHub Repository Interactive Selection
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2025-11-29
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Spec follows the same pattern as 002-jira-integration FR-009a
+- UX consistency with select_jira_projects is explicitly required
+- API endpoints mentioned (GET /user/repos, GET /orgs/{org}/repos) are part of the functional description, not implementation details
+- Ready for `/speckit.plan` or `/speckit.clarify`

specs/004-github-repo-selection/contracts/github-api.yaml

@@ -0,0 +1,189 @@
+# GitHub API Contract for Repository Listing
+# Feature: 004-github-repo-selection
+# These are the external GitHub API endpoints used by this feature
+
+openapi: 3.0.3
+info:
+  title: GitHub API - Repository Endpoints (Subset)
+  version: 2022-11-28
+  description: |
+    External API contracts for GitHub repository listing.
+    This documents the subset of GitHub REST API used by the
+    interactive repository selection feature.
+
+paths:
+  /user/repos:
+    get:
+      operationId: listUserRepos
+      summary: List repositories for the authenticated user
+      description: |
+        Lists repositories that the authenticated user has explicit permission
+        to access. Used for FR-005 (personal repository listing).
+      parameters:
+        - name: affiliation
+          in: query
+          description: |
+            Comma-separated list of values. Can include: owner, collaborator,
+            organization_member. Feature uses "owner,collaborator" per spec clarification.
+          schema:
+            type: string
+            default: "owner,collaborator,organization_member"
+          example: "owner,collaborator"
+        - name: visibility
+          in: query
+          description: Filter by visibility
+          schema:
+            type: string
+            enum: [all, public, private]
+            default: all
+        - name: sort
+          in: query
+          schema:
+            type: string
+            enum: [created, updated, pushed, full_name]
+            default: full_name
+        - name: direction
+          in: query
+          schema:
+            type: string
+            enum: [asc, desc]
+            default: asc
+        - name: per_page
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 30
+        - name: page
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            default: 1
+      responses:
+        '200':
+          description: List of repositories
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Repository'
+        '401':
+          description: Authentication required
+        '403':
+          description: Rate limit exceeded or insufficient permissions
+
+  /orgs/{org}/repos:
+    get:
+      operationId: listOrgRepos
+      summary: List organization repositories
+      description: |
+        Lists repositories for the specified organization. Used for FR-006.
+      parameters:
+        - name: org
+          in: path
+          required: true
+          description: The organization name (case-insensitive)
+          schema:
+            type: string
+            pattern: "^[a-zA-Z0-9]([a-zA-Z0-9-]{0,37}[a-zA-Z0-9])?$"
+        - name: type
+          in: query
+          description: Repository type filter
+          schema:
+            type: string
+            enum: [all, public, private, forks, sources, member]
+            default: all
+        - name: sort
+          in: query
+          schema:
+            type: string
+            enum: [created, updated, pushed, full_name]
+            default: created
+        - name: direction
+          in: query
+          schema:
+            type: string
+            enum: [asc, desc]
+        - name: per_page
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 30
+        - name: page
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            default: 1
+      responses:
+        '200':
+          description: List of repositories
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Repository'
+        '404':
+          description: Organization not found
+
+components:
+  schemas:
+    Repository:
+      type: object
+      description: GitHub repository (minimal fields used by feature)
+      required:
+        - id
+        - full_name
+        - name
+        - owner
+        - private
+        - fork
+      properties:
+        id:
+          type: integer
+          description: Unique repository ID
+        full_name:
+          type: string
+          description: Full repository name (owner/repo)
+          example: "octocat/Hello-World"
+        name:
+          type: string
+          description: Repository name
+          example: "Hello-World"
+        owner:
+          $ref: '#/components/schemas/Owner'
+        description:
+          type: string
+          nullable: true
+          description: Repository description
+        private:
+          type: boolean
+          description: Whether repository is private
+        fork:
+          type: boolean
+          description: Whether repository is a fork
+        html_url:
+          type: string
+          format: uri
+          description: GitHub URL for repository
+
+    Owner:
+      type: object
+      required:
+        - login
+      properties:
+        login:
+          type: string
+          description: Owner username/org name
+          example: "octocat"
+        id:
+          type: integer
+        type:
+          type: string
+          enum: [User, Organization]