fix(cli): prevent hang in pre-commit hooks by using dynamic imports

[TabishB]

Summary

Fixes #367

• Convert static @inquirer/prompts imports to dynamic imports, loaded only when interactive prompts are actually needed
• Dynamically import InitCommand (which uses @inquirer/core) to prevent loading at startup
• Update isInteractive() to accept options object supporting both noInteractive and Commander's negated interactive property
• Handle empty validation queue with proper JSON output and exit code

Root Cause

The CLI hung when run as a pre-commit hook because @inquirer/prompts was statically imported at module load time. Even when prompts were never called (e.g., openspec validate --specs --no-interactive), the import could set up stdin references that prevented clean process exit when stdin was piped.

The workaround discovered by @greenkiwi (0<&- to close stdin) confirmed the issue was stdin-related.

Test plan

• Run openspec validate --specs --strict --no-interactive in a pre-commit hook - should complete without hanging
• Verify interactive mode still works when running from terminal
• Run existing test suite to ensure no regressions

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

• Refactor

  • Optimized prompt initialization for improved performance by deferring module loading until needed.

• New Features

  • Enhanced validation output with comprehensive result summaries.
  • Improved JSON output structure for validation results.

• Bug Fixes

  • Better handling of edge cases when no items are available for validation.
  • Improved consistency of exit codes and output formatting across validation modes.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

This pull request refactors how inquirer prompt modules are imported and how interactive mode is detected across the codebase. Static top-level imports of select and confirm from @inquirer/prompts are replaced with dynamic imports that load only when needed. The interactive mode detection logic is consolidated, allowing the isInteractive function to accept either a boolean or an options object instead of just the noInteractive flag, addressing issues with prompts hanging in non-interactive environments like pre-commit hooks.

Changes

Cohort / File(s)	Summary
Lazy-loaded prompt imports src/commands/change.ts, src/commands/completion.ts, src/commands/show.ts, src/commands/spec.ts, src/core/archive.ts	Removed top-level static imports of select and/or confirm from @inquirer/prompts and replaced with dynamic imports within conditional code paths that require user prompts.
Interactive mode detection refactor src/cli/index.ts, src/commands/change.ts, src/commands/show.ts, src/commands/spec.ts, src/commands/validate.ts, src/utils/interactive.ts	Updated calls to isInteractive() to pass the entire options object instead of just options?.noInteractive. Expanded the isInteractive function signature to accept value?: boolean | InteractiveOptions and introduced new internal types and resolver logic.
Validation command restructuring src/commands/validate.ts	Added lazy import of select, early exit handling for empty item lists, new private methods normalizeType() and runInteractiveSelector(), and improved result accumulation with JSON output structure including version field.
Color flag handling src/cli/index.ts	Changed global preAction color flag check from opts.noColor to opts.color === false for flag interpretation.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Areas requiring extra attention:

• src/commands/validate.ts: Contains the most substantial logic changes including new private methods, early exit handling, result aggregation, and JSON output structure—requires verification that all validation flows (bulk, interactive, single-item) correctly handle empty and non-empty cases.
• src/utils/interactive.ts: The expanded signature and new resolveNoInteractive logic should be verified against all call sites to ensure the parameter passing from refactored commands correctly interprets interactive/non-interactive state.
• Dynamic import error handling: Across all refactored files, verify that the lazy-loaded imports handle potential failures gracefully (especially in paths where prompts are conditionally loaded).

Poem

🐰 Lazy loading hops in light,
No prompts hanging in the night,
Dynamic imports, sleek and keen,
Interactive paths now clean,
Pre-commit hooks skip the delay—
Prompts only when we need to play! ✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main objective of the PR: converting static imports to dynamic imports to prevent CLI hangs in pre-commit hooks.
Linked Issues check	✅ Passed	The PR implementation addresses all coding requirements from #367: dynamic imports for @inquirer/prompts and InitCommand, updated isInteractive() logic, and proper handling of empty validation queues.
Out of Scope Changes check	✅ Passed	All changes are directly related to the stated objectives. The refactoring of interactive mode checks to use options objects instead of just noInteractive flag is a necessary supporting change.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch TabishB/issue367-debug

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f39cc5c and 03ea323.

📒 Files selected for processing (8)

• src/cli/index.ts (2 hunks)
• src/commands/change.ts (2 hunks)
• src/commands/completion.ts (1 hunks)
• src/commands/show.ts (2 hunks)
• src/commands/spec.ts (3 hunks)
• src/commands/validate.ts (3 hunks)
• src/core/archive.ts (4 hunks)
• src/utils/interactive.ts (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (4)

src/commands/change.ts (2)

src/utils/interactive.ts (1)

• isInteractive (17-21)

src/utils/item-discovery.ts (1)

• getActiveChangeIds (4-23)

src/commands/spec.ts (2)

src/utils/interactive.ts (1)

• isInteractive (17-21)

src/utils/item-discovery.ts (1)

• getSpecIds (25-44)

src/commands/show.ts (1)

src/utils/interactive.ts (1)

• isInteractive (17-21)

src/commands/validate.ts (1)

src/utils/interactive.ts (1)

• isInteractive (17-21)

🔇 Additional comments (17)

src/cli/index.ts (2)

32-34: LGTM — Correct handling of Commander's negated option pattern.

Commander transforms --no-color into opts.color = false, so checking opts.color === false is the correct approach for detecting when color should be disabled.

---

65-69: LGTM — Dynamic import prevents stdin hang in non-interactive contexts.

Lazy-loading InitCommand at runtime (instead of statically importing at module load) ensures that @inquirer/core dependencies within InitCommand are not loaded when the CLI runs in non-interactive environments like pre-commit hooks. This directly addresses the root cause in issue #367.

src/utils/interactive.ts (1)

1-21: LGTM — Clean abstraction for dual-path interactive detection.

The resolveNoInteractive helper elegantly handles both the legacy noInteractive: true pattern and Commander's negated option (--no-interactive → interactive: false). This enables callers to pass the entire options object without manual property extraction.

One note: the environment variable is OPEN_SPEC_INTERACTIVE here, while the issue mentions OPENSPEC_NO_INTERACTIVE. Verify this is intentional and document the supported env var(s) if both are valid.

src/commands/change.ts (2)

32-40: LGTM — Consistent migration to dynamic import pattern.

The isInteractive(options) call correctly leverages the new API that accepts the full options object, and the dynamic import of select is properly guarded within the interactive code path.

---

189-197: LGTM — Same dynamic import pattern applied consistently.

The validate method follows the identical pattern as show, ensuring @inquirer/prompts is only loaded when interactive prompts are actually needed.

src/commands/completion.ts (1)

180-191: LGTM — Dynamic import correctly scoped to confirmation path.

The confirm prompt is only imported when confirmation is actually needed (i.e., when skipConfirmation is false), preventing unnecessary module loading when --yes is passed.

src/commands/spec.ts (2)

72-79: LGTM — Dynamic import pattern applied to spec show.

The isInteractive(options) call and dynamic select import are correctly implemented within the interactive code path.

---

207-214: LGTM — Consistent pattern in spec validate action.

Same correct pattern applied to the validate command's interactive selector.

src/commands/show.ts (2)

15-27: LGTM — Dynamic import in execute's interactive path.

The isInteractive(options) call and the dynamic select import are correctly placed within the interactive code path.

---

47-55: LGTM — Dynamic import in runInteractiveByType.

The select prompt is dynamically imported at the start of this method, which is only called from interactive paths. The import is used for both the change and spec selection prompts within this method.

src/core/archive.ts (4)

127-141: LGTM — Dynamic import for validation skip confirmation.

The confirm prompt is correctly imported within the confirmation path when validation is skipped.

---

151-164: LGTM — Dynamic import for incomplete tasks confirmation.

Same pattern correctly applied for the incomplete tasks warning prompt.

---

182-191: LGTM — Dynamic import for spec update confirmation.

Same pattern correctly applied for the spec updates confirmation prompt.

---

260-302: LGTM — Dynamic import in selectChange.

The select prompt is dynamically imported within selectChange, which is only called when interactive change selection is needed.

src/commands/validate.ts (3)

31-31: LGTM — Updated to use new isInteractive API.

Correctly passes the full options object to isInteractive().

---

65-92: LGTM — Dynamic import in interactive selector.

The select prompt is dynamically imported within the interactive selector method, preventing module load at startup.

---

215-235: LGTM — Proper handling of empty validation queue.

This correctly addresses the PR objective of handling empty validation queues with:

• Proper JSON output structure (including version field and empty items array)
• Clear text message for non-JSON mode
• Exit code 0 (success) since "nothing to validate" is not an error condition

This ensures the CLI exits cleanly in pre-commit hooks when no items match the validation criteria.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}