CLI: Decide and implement an optional interactive shell

[bcherrington]

Current state and decision

TimeLocker supports interactive prompts and wizards inside individual commands, but it does not provide a repository-wide REPL or tl shell. This is an optional feature and is not part of the v0.9.1 stabilization milestone.

Acceptance criteria

• Confirm user need and define why a shell is preferable to existing command help, completion, and wizards.
• If approved, implement an opt-in shell with history, contextual completion, help, and safe interruption.
• Preserve identical non-interactive command semantics and require previews or confirmations for destructive operations.
• Resolve credentials only when needed and suppress sensitive or noisy completion output.
• Add unit and subprocess integration tests plus a concise user guide.

Sequencing

Defer until after v0.9.1 release stabilization unless explicitly reprioritized.

[github-actions]

🔍 Issue Triage Analysis

Priority Level: Medium

Rationale: This is a valuable UX enhancement that improves discoverability and user experience, but it's not critical for core functionality. It's a "nice-to-have" feature that can significantly improve developer productivity.

Issue Type: Enhancement/Feature Request

Category: User Experience Enhancement

Complexity Estimate: Medium-Complex

Rationale:

• Requires implementing a REPL (Read-Eval-Print Loop) system
• Integration with existing Typer CLI structure
• Command history and completion systems
• Credential service integration for non-interactive flows
• Testing across multiple interaction patterns

Suggested Labels:

• ✅ enhancement (already applied)
• ✅ area:cli (already applied)
• 🆕 priority:medium
• 🆕 complexity:medium
• 🆕 feature:interactive

Team/Component: CLI/UX Team

Primary Areas: CLI interface, user experience, completion systems

Dependencies Analysis:

Blocking Dependencies:

• Issue Security: Reconcile the repository credential resolution contract #28: "Security: Integrate Credential Service with CLI and per-repo secrets" - CRITICAL DEPENDENCY
  • Interactive mode requires proper credential handling
  • Must support non-interactive credential fetching as specified
  • Current CLI already has some credential integration, but Security: Reconcile the repository credential resolution contract #28 addresses full integration

Recommended Dependencies (not blocking but beneficial):

• Issue CLI: Complete remaining documented command behavior #5: "CLI: Implement missing functionality for stub commands" - Should complete core CLI before adding interactive layer
• Issue CLI: Update shell completion scripts for new command hierarchy #13: "CLI: Update shell completion scripts" - Completion improvements would enhance interactive experience

Technical Implementation Considerations:

Current State Analysis:

• ✅ Typer-based CLI structure already in place
• ✅ Rich console integration available
• ✅ Completion system exists (completion.py)
• ✅ Credential manager infrastructure present
• ❌ No existing REPL/interactive shell implementation

Implementation Approach:

1. REPL Library: Consider using prompt_toolkit (not currently in dependencies) or building on existing Rich/Typer infrastructure
2. Command Integration: Leverage existing Typer app structure for command dispatch
3. History: Implement command history persistence
4. Completion: Extend existing completion system for interactive context
5. Credential Handling: Integrate with existing credential service (depends on Security: Reconcile the repository credential resolution contract #28)

Acceptance Criteria Assessment:

• ✅ Well-defined: Clear requirements for tl shell/tl interactive command
• ✅ Testable: Specific testing requirements outlined
• ✅ Measurable: Clear success criteria for REPL functionality
• ⚠️ Dependency on Security: Reconcile the repository credential resolution contract #28: Credential service integration requirement

Reproducibility: N/A (Feature Request)

Similar Issues:

No direct duplicates found. Related UX enhancement issues exist but focus on different aspects of CLI experience.

📋 Recommendations

Next Steps:

1. Dependency Resolution: Complete Issue Security: Reconcile the repository credential resolution contract #28 (Credential Service integration) first
2. Technical Spike: Research REPL implementation options (prompt_toolkit vs custom)
3. Design Review: Create detailed technical design for interactive mode
4. Prototype: Build minimal viable interactive shell
5. Integration: Full implementation with testing

Additional Information Needed:

• Library Dependencies: Decision on whether to add prompt_toolkit or similar REPL library
• User Experience Design: Mockups or detailed UX flow for interactive mode
• Performance Requirements: Expected response time for command completion in interactive mode

Potential Assignees:

• CLI/UX developers familiar with Typer and Rich
• Developers experienced with REPL implementations
• Team members working on credential service integration

Immediate Actions:

• Add recommended labels
• Link to Issue Security: Reconcile the repository credential resolution contract #28 as blocking dependency
• Consider adding to CLI enhancement milestone
• Evaluate if this should be part of v1.0.0 or deferred to v1.1.0

Risk Assessment: Low-Medium

• Risk: Adding complexity to CLI startup time
• Mitigation: Lazy loading of interactive components
• Risk: Credential handling in interactive context
• Mitigation: Proper integration with credential service (Issue Security: Reconcile the repository credential resolution contract #28)

---

This analysis was generated on 2025-09-27. The issue appears well-scoped and valuable for user experience, with clear implementation path once dependencies are resolved.

[github-actions]

🔍 Issue Triage Analysis

Priority Level: Medium

• Urgency: Low - This is an enhancement that improves user experience but doesn't block core functionality
• Impact: Medium - Would significantly improve CLI usability and user experience for interactive workflows

Issue Type: Enhancement/Feature Request

• New interactive shell/REPL functionality for TimeLocker CLI
• User experience improvement for command discovery and guided workflows

Complexity Estimate: Medium-Complex

• Technical Complexity: Medium - Requires implementing REPL infrastructure with history, completion, and command integration
• Integration Complexity: Medium - Must integrate with existing Typer CLI structure and maintain non-interactive compatibility
• Testing Complexity: Medium - Requires both unit tests for REPL components and integration tests for interactive flows

Suggested Labels:

• ✅ enhancement (already applied)
• ✅ area:cli (already applied)
• 🆕 priority:medium
• 🆕 complexity:medium
• 🆕 feature:interactive
• 🆕 good-first-issue (could be suitable for contributors familiar with Python CLI development)

Team/Component: CLI Team

• Primary Component: CLI interface (src/TimeLocker/cli.py)
• Related Components:
  • Completion system (src/TimeLocker/completion.py)
  • Credential Service (for on-demand credential fetching)
  • Logging system (for suppression during completion)

Dependencies:

• Soft Dependency: Issue Security: Reconcile the repository credential resolution contract #28 (Credential Service integration) - for on-demand credential fetching without password warnings
• Related: Issues CLI: Complete remaining documented command behavior #5-Testing: Create comprehensive test suite for new CLI command structure #8 (CLI implementation and testing) - should be completed first for stable foundation
• Library Dependencies: May require adding prompt_toolkit or similar REPL library to dependencies

Reproducibility: N/A (Feature Request)

• Clear acceptance criteria provided
• Well-defined scope and requirements

Acceptance Criteria Assessment: ✅ Well-Defined

• ✅ Clear command specification (tl shell or tl interactive)
• ✅ Specific technical requirements (REPL with help, history, completion)
• ✅ Integration requirements (all commands available, dry-run preview)
• ✅ Security requirements (no password warnings, on-demand credentials)
• ✅ Testing requirements (unit + integration tests)
• ✅ Documentation requirements (examples included)

Similar Issues:

• Related to CLI completion work (already implemented)
• Builds on existing interactive features like targets edit --interactive (line 4512 in cli.py)
• Complements the existing config setup interactive wizard

📋 Recommendations

Next Steps:

1. Research Phase: Evaluate REPL libraries (prompt_toolkit, cmd, or custom implementation)
2. Design Phase: Create detailed design for REPL integration with existing Typer structure
3. Dependency Planning: Determine if new dependencies need to be added to pyproject.toml
4. Implementation Planning: Break down into smaller tasks (REPL core, command integration, completion, testing)

Additional Information Needed:

• User Experience: Should the REPL support command history persistence across sessions?
• Command Scope: Should all CLI commands be available or a subset optimized for interactive use?
• Exit Strategy: How should users exit the interactive shell (standard exit, quit, Ctrl+D)?

Potential Assignees:

• CLI team members familiar with Python REPL development
• Contributors with experience in prompt_toolkit or similar libraries
• Team members who worked on existing interactive features

Implementation Notes:

• Current CLI uses Typer framework with Rich for output
• Existing completion system is already implemented and can be leveraged
• Interactive editing pattern already exists in targets edit --interactive
• Credential Service integration (Issue Security: Reconcile the repository credential resolution contract #28) should be prioritized for seamless experience

Risk Assessment: Low

• Non-breaking change (additive feature)
• Well-isolated functionality
• Clear fallback to existing non-interactive behavior

---

Recommendation: Approve for development after Issues #5-#8 (CLI foundation) are completed. Consider as a good candidate for community contribution with proper mentoring.

[bcherrington]

Reconciled on 2026-07-18. Retained as a deferred product decision; current prompt helpers do not satisfy the requested REPL.