Improve error handling and error readability for all commands

[ivanvpetrov]

Closes #1610
Closes #1612

fix(cli): improve error handling and error readability for all commands

Summary

This PR improves the error handling and user-facing error messages across all ig CLI commands. Previously, certain invalid inputs would either crash with a raw Node.js stack trace or silently fall through to interactive mode — both confusing for the user.

---

Changes

Error handling for command validation failures

Added a .fail() handler to the yargs instance in cli.ts. When a command fails its own validation (e.g. ig generate without providing a required subcommand), yargs previously threw an unhandled exception resulting in a stack trace. Now the user sees a clear error message and the relevant help output.

Before:
P.n.fail ... Object.nonOptionCount ... (stack trace)

After:
Please select command

Commands:
generate template [name] generates custom template

---

Unknown command detection

Running ig <unknown> previously silently dropped into the step-by-step interactive mode as if no command was provided. The interactive mode now only activates when the user runs ig with no arguments at all — the intentional entry point. Providing an unrecognized command now gives explicit feedback.

Before:
Starting Step by step mode...
? Enter a name for your project:

After:
Unknown command: "asdf"
(+ help listing all available commands)

---

Unhandled promise rejection in entry point

Added a .catch() on the cli.run() call in execute.js so that any unexpected async errors produce a clean Error: <message> output instead of a Node.js unhandled rejection crash.

---

Tests

Updated and extended spec/unit/cli-spec.ts:

• Updated "Should fire properly - fallback to default" — now explicitly passes empty args to confirm step-by-step mode is only triggered with no input
• Added "Should show error for unknown command" — verifies Util.error is called with the unknown command name and the prompt session is not started
• Added "Should gracefully handle subcommand validation errors" — verifies the .fail() handler surfaces the yargs demandCommand message instead of crashing

[Copilot]

Pull request overview

This PR improves ig CLI UX by replacing stack traces and unintended interactive fallbacks with clearer error messages, help output, and a catch-all async error handler at the entry point.

Changes:

• Add a yargs .fail() handler to surface validation errors cleanly and show help.
• Treat unknown commands as errors (with help) and only enter interactive mode when invoked with no args.
• Catch unexpected async errors in the CLI entry point and exit with failure.

Reviewed changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated 4 comments.

File	Description
packages/cli/lib/cli.ts	Adds yargs failure handling and differentiates unknown-command vs no-args interactive fallback.
packages/cli/bin/execute.js	Wraps cli.run() with a .catch() to avoid unhandled rejection crashes and exit non-zero.
spec/unit/cli-spec.ts	Updates/extends unit coverage for no-args fallback, unknown command error, and validation failures.
CHANGELOG.md	Documents the CLI error-handling fixes and behavior changes.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coveralls]

coverage: 86.079% (-0.02%) from 86.103% — ipetrov/error-handing-improvement into master

[Copilot]

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• www.google-analytics.com
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node packages/cli/bin/execute.js new --help (dns block)
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node packages/cli/bin/execute.js config --help de_modules/.bin/tsx (dns block)
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node packages/cli/bin/execute.js generate --help de_modules/.bin/tsx (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[Copilot]

Pull request overview

Copilot reviewed 3 out of 4 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.