fix(cli): report built-in command errors instead of crashing

[ankitranjan7]

Finding #1 from the CLI audit. Independent of #361 — branched from main, no overlapping hunks.

The bug

runCli was createProgram(...).parse() with no error handling. Anything a built-in command threw escaped: sync throws printed a raw Node stack trace, async ones surfaced as unhandled rejections, and either way the exitCode the error carried was thrown away.

$ webcmd adapter path hackernews/top
file:///…/dist/src/cli.js:1635
throw new ArgumentError(`Adapter source is unavailable …`);
^
ArgumentError: Adapter source is unavailable for hackernews/top.
at localAdapterPath (file:///…/dist/src/cli.js:1635:19)
…

Adapter commands never had this problem — execution.ts wraps them and renders the shared error envelope. Only built-ins were unprotected.

Five commands this fixes

command	before	after
adapter path <site>/<cmd>	stack trace, exit 1	envelope, exit 2
adapter source get <site>/<cmd>	stack trace, exit 1	envelope, exit 2
adapter source put <a>/<b> <path>	stack trace, exit 1	envelope, exit 2
site fixture get <site>/<cmd>	stack trace, exit 1	envelope, exit 66
session close <bad-id>	stack trace, exit 1	envelope, exit 2

$ webcmd adapter path hackernews/top
ok: false
error:
code: ARGUMENT
message: Adapter source is unavailable for hackernews/top.
exitCode: 2
$ webcmd session close bogus
ok: false
error:
code: INVALID_SESSION_SELECTOR
message: 'Session selector must be an opaque Session ID: bogus'
help: Run `webcmd session create` and pass the returned `session_...` ID.
exitCode: 2

Same envelope adapters already emit, on stderr, so an agent parses built-in and adapter failures the same way. Exit codes now come from the error instead of being lost, which finally applies the taxonomy already declared in errors.ts — site fixture get on a missing fixture exits 66 (EMPTY_RESULT), not 1.

Stacks stay off unless WEBCMD_DEBUG is set.

Reuse, not new machinery

toEnvelope() (errors.ts) and formatErrorEnvelope() (output.ts) already existed and are what commanderAdapter.ts uses for adapter errors. reportCliError just wires them to the built-in path; it takes an injectable stream so it is directly testable.

Two consequences worth reviewing

parse() → parseAsync(), and main.ts awaits. This is what lets an async rejection reach the handler at all.

Signal cancellation now covers the actual run.parse() returned as soon as it kicked off an async action, so main.ts's finally { uninstallSignalCancellation() } tore down the SIGINT handler while the run was still in flight — Ctrl-C during an adapter run never cancelled the daemon run. Awaiting keeps it installed for the real duration. This is a behaviour fix that falls out of the same change; calling it out because it is not obvious from the diff.

Verification

• npm run typecheck — clean
• npm test — 5687 passed, 1 failed: src/doctor.test.ts:218 (profile alias rendering), pre-existing on main, unrelated
• All five commands above exercised against a local build; exit codes confirmed with $?
• Happy paths re-checked (hackernews top, list, --help) — still exit 0
• New src/cli-error-report.test.ts covers the envelope, the hint, the UNKNOWN fallback, and the WEBCMD_DEBUG stack toggle

Tests went in a new file rather than cli.test.ts so this branch and #361 stay conflict-free.

Not in this PR

adapter path still fails for every command that is not already a local override (finding #2) — that is a separate bug in resolveAdapterSourcePath. This PR makes it report the failure properly instead of crashing; it does not make the command work.

🤖 Generated with Claude Code

[github-actions]

🟠 Maintainer review suggested — low confidence

The automated review could not reach a fully supported conclusion.

Limitations

• The automated review returned an invalid structured result.

This review is advisory and does not block merging.

[ankitranjan7]

Finding #1 from the CLI audit. Independent of #361 — branched from main, no overlapping hunks.

The bug

runCli was createProgram(...).parse() with no error handling. Anything a built-in command threw escaped: sync throws printed a raw Node stack trace, async ones surfaced as unhandled rejections, and either way the exitCode the error carried was thrown away.

$ webcmd adapter path hackernews/top
file:///…/dist/src/cli.js:1635
throw new ArgumentError(`Adapter source is unavailable …`);
^
ArgumentError: Adapter source is unavailable for hackernews/top.
at localAdapterPath (file:///…/dist/src/cli.js:1635:19)
…

Adapter commands never had this problem — execution.ts wraps them and renders the shared error envelope. Only built-ins were unprotected.

Five commands this fixes

command	before	after
adapter path <site>/<cmd>	stack trace, exit 1	envelope, exit 2
adapter source get <site>/<cmd>	stack trace, exit 1	envelope, exit 2
adapter source put <a>/<b> <path>	stack trace, exit 1	envelope, exit 2
site fixture get <site>/<cmd>	stack trace, exit 1	envelope, exit 66
session close <bad-id>	stack trace, exit 1	envelope, exit 2

$ webcmd adapter path hackernews/top
ok: false
error:
code: ARGUMENT
message: Adapter source is unavailable for hackernews/top.
exitCode: 2
$ webcmd session close bogus
ok: false
error:
code: INVALID_SESSION_SELECTOR
message: 'Session selector must be an opaque Session ID: bogus'
help: Run `webcmd session create` and pass the returned `session_...` ID.
exitCode: 2

Same envelope adapters already emit, on stderr, so an agent parses built-in and adapter failures the same way. Exit codes now come from the error instead of being lost, which finally applies the taxonomy already declared in errors.ts — site fixture get on a missing fixture exits 66 (EMPTY_RESULT), not 1.

Stacks stay off unless WEBCMD_DEBUG is set.

Reuse, not new machinery

toEnvelope() (errors.ts) and formatErrorEnvelope() (output.ts) already existed and are what commanderAdapter.ts uses for adapter errors. reportCliError just wires them to the built-in path; it takes an injectable stream so it is directly testable.

Two consequences worth reviewing

parse() → parseAsync(), and main.ts awaits. This is what lets an async rejection reach the handler at all.

Signal cancellation now covers the actual run.parse() returned as soon as it kicked off an async action, so main.ts's finally { uninstallSignalCancellation() } tore down the SIGINT handler while the run was still in flight — Ctrl-C during an adapter run never cancelled the daemon run. Awaiting keeps it installed for the real duration. This is a behaviour fix that falls out of the same change; calling it out because it is not obvious from the diff.

Verification

• npm run typecheck — clean
• npm test — 5687 passed, 1 failed: src/doctor.test.ts:218 (profile alias rendering), pre-existing on main, unrelated
• All five commands above exercised against a local build; exit codes confirmed with $?
• Happy paths re-checked (hackernews top, list, --help) — still exit 0
• New src/cli-error-report.test.ts covers the envelope, the hint, the UNKNOWN fallback, and the WEBCMD_DEBUG stack toggle

Tests went in a new file rather than cli.test.ts so this branch and #361 stay conflict-free.

Not in this PR

adapter path still fails for every command that is not already a local override (finding #2) — that is a separate bug in resolveAdapterSourcePath. This PR makes it report the failure properly instead of crashing; it does not make the command work.

🤖 Generated with Claude Code

[github-actions]

🟠 Maintainer review suggested — low confidence

The automated review could not reach a fully supported conclusion.

Limitations

• The automated review returned an invalid structured result.

This review is advisory and does not block merging.

[ankitranjan7]

Finding #1 from the CLI audit. Independent of #361 — branched from main, no overlapping hunks.

The bug

runCli was createProgram(...).parse() with no error handling. Anything a built-in command threw escaped: sync throws printed a raw Node stack trace, async ones surfaced as unhandled rejections, and either way the exitCode the error carried was thrown away.

$ webcmd adapter path hackernews/top
file:///…/dist/src/cli.js:1635
throw new ArgumentError(`Adapter source is unavailable …`);
^
ArgumentError: Adapter source is unavailable for hackernews/top.
at localAdapterPath (file:///…/dist/src/cli.js:1635:19)
…

Adapter commands never had this problem — execution.ts wraps them and renders the shared error envelope. Only built-ins were unprotected.

Five commands this fixes

command	before	after
adapter path <site>/<cmd>	stack trace, exit 1	envelope, exit 2
adapter source get <site>/<cmd>	stack trace, exit 1	envelope, exit 2
adapter source put <a>/<b> <path>	stack trace, exit 1	envelope, exit 2
site fixture get <site>/<cmd>	stack trace, exit 1	envelope, exit 66
session close <bad-id>	stack trace, exit 1	envelope, exit 2

$ webcmd adapter path hackernews/top
ok: false
error:
code: ARGUMENT
message: Adapter source is unavailable for hackernews/top.
exitCode: 2
$ webcmd session close bogus
ok: false
error:
code: INVALID_SESSION_SELECTOR
message: 'Session selector must be an opaque Session ID: bogus'
help: Run `webcmd session create` and pass the returned `session_...` ID.
exitCode: 2

Same envelope adapters already emit, on stderr, so an agent parses built-in and adapter failures the same way. Exit codes now come from the error instead of being lost, which finally applies the taxonomy already declared in errors.ts — site fixture get on a missing fixture exits 66 (EMPTY_RESULT), not 1.

Stacks stay off unless WEBCMD_DEBUG is set.

Reuse, not new machinery

toEnvelope() (errors.ts) and formatErrorEnvelope() (output.ts) already existed and are what commanderAdapter.ts uses for adapter errors. reportCliError just wires them to the built-in path; it takes an injectable stream so it is directly testable.

Two consequences worth reviewing

parse() → parseAsync(), and main.ts awaits. This is what lets an async rejection reach the handler at all.

Signal cancellation now covers the actual run.parse() returned as soon as it kicked off an async action, so main.ts's finally { uninstallSignalCancellation() } tore down the SIGINT handler while the run was still in flight — Ctrl-C during an adapter run never cancelled the daemon run. Awaiting keeps it installed for the real duration. This is a behaviour fix that falls out of the same change; calling it out because it is not obvious from the diff.

Verification

• npm run typecheck — clean
• npm test — 5687 passed, 1 failed: src/doctor.test.ts:218 (profile alias rendering), pre-existing on main, unrelated
• All five commands above exercised against a local build; exit codes confirmed with $?
• Happy paths re-checked (hackernews top, list, --help) — still exit 0
• New src/cli-error-report.test.ts covers the envelope, the hint, the UNKNOWN fallback, and the WEBCMD_DEBUG stack toggle

Tests went in a new file rather than cli.test.ts so this branch and #361 stay conflict-free.

Not in this PR

adapter path still fails for every command that is not already a local override (finding #2) — that is a separate bug in resolveAdapterSourcePath. This PR makes it report the failure properly instead of crashing; it does not make the command work.

🤖 Generated with Claude Code

[github-actions]

🟠 Maintainer review suggested — low confidence

The automated review could not reach a fully supported conclusion.

Limitations

• The automated review returned an invalid structured result.

This review is advisory and does not block merging.

[ankitranjan7]

Finding #1 from the CLI audit. Independent of #361 — branched from main, no overlapping hunks.

The bug

runCli was createProgram(...).parse() with no error handling. Anything a built-in command threw escaped: sync throws printed a raw Node stack trace, async ones surfaced as unhandled rejections, and either way the exitCode the error carried was thrown away.

$ webcmd adapter path hackernews/top
file:///…/dist/src/cli.js:1635
throw new ArgumentError(`Adapter source is unavailable …`);
^
ArgumentError: Adapter source is unavailable for hackernews/top.
at localAdapterPath (file:///…/dist/src/cli.js:1635:19)
…

Adapter commands never had this problem — execution.ts wraps them and renders the shared error envelope. Only built-ins were unprotected.

Five commands this fixes

command	before	after
adapter path <site>/<cmd>	stack trace, exit 1	envelope, exit 2
adapter source get <site>/<cmd>	stack trace, exit 1	envelope, exit 2
adapter source put <a>/<b> <path>	stack trace, exit 1	envelope, exit 2
site fixture get <site>/<cmd>	stack trace, exit 1	envelope, exit 66
session close <bad-id>	stack trace, exit 1	envelope, exit 2

$ webcmd adapter path hackernews/top
ok: false
error:
code: ARGUMENT
message: Adapter source is unavailable for hackernews/top.
exitCode: 2
$ webcmd session close bogus
ok: false
error:
code: INVALID_SESSION_SELECTOR
message: 'Session selector must be an opaque Session ID: bogus'
help: Run `webcmd session create` and pass the returned `session_...` ID.
exitCode: 2

Same envelope adapters already emit, on stderr, so an agent parses built-in and adapter failures the same way. Exit codes now come from the error instead of being lost, which finally applies the taxonomy already declared in errors.ts — site fixture get on a missing fixture exits 66 (EMPTY_RESULT), not 1.

Stacks stay off unless WEBCMD_DEBUG is set.

Reuse, not new machinery

toEnvelope() (errors.ts) and formatErrorEnvelope() (output.ts) already existed and are what commanderAdapter.ts uses for adapter errors. reportCliError just wires them to the built-in path; it takes an injectable stream so it is directly testable.

Two consequences worth reviewing

parse() → parseAsync(), and main.ts awaits. This is what lets an async rejection reach the handler at all.

Signal cancellation now covers the actual run.parse() returned as soon as it kicked off an async action, so main.ts's finally { uninstallSignalCancellation() } tore down the SIGINT handler while the run was still in flight — Ctrl-C during an adapter run never cancelled the daemon run. Awaiting keeps it installed for the real duration. This is a behaviour fix that falls out of the same change; calling it out because it is not obvious from the diff.

Verification

• npm run typecheck — clean
• npm test — 5687 passed, 1 failed: src/doctor.test.ts:218 (profile alias rendering), pre-existing on main, unrelated
• All five commands above exercised against a local build; exit codes confirmed with $?
• Happy paths re-checked (hackernews top, list, --help) — still exit 0
• New src/cli-error-report.test.ts covers the envelope, the hint, the UNKNOWN fallback, and the WEBCMD_DEBUG stack toggle

Tests went in a new file rather than cli.test.ts so this branch and #361 stay conflict-free.

Not in this PR

adapter path still fails for every command that is not already a local override (finding #2) — that is a separate bug in resolveAdapterSourcePath. This PR makes it report the failure properly instead of crashing; it does not make the command work.

🤖 Generated with Claude Code

[github-actions]

🟠 Maintainer review suggested — low confidence

The automated review could not reach a fully supported conclusion.

Limitations

• The automated review returned an invalid structured result.

This review is advisory and does not block merging.

[ankitranjan7]

Finding #1 from the CLI audit. Independent of #361 — branched from main, no overlapping hunks.

The bug

runCli was createProgram(...).parse() with no error handling. Anything a built-in command threw escaped: sync throws printed a raw Node stack trace, async ones surfaced as unhandled rejections, and either way the exitCode the error carried was thrown away.

$ webcmd adapter path hackernews/top
file:///…/dist/src/cli.js:1635
throw new ArgumentError(`Adapter source is unavailable …`);
^
ArgumentError: Adapter source is unavailable for hackernews/top.
at localAdapterPath (file:///…/dist/src/cli.js:1635:19)
…

Adapter commands never had this problem — execution.ts wraps them and renders the shared error envelope. Only built-ins were unprotected.

Five commands this fixes

command	before	after
adapter path <site>/<cmd>	stack trace, exit 1	envelope, exit 2
adapter source get <site>/<cmd>	stack trace, exit 1	envelope, exit 2
adapter source put <a>/<b> <path>	stack trace, exit 1	envelope, exit 2
site fixture get <site>/<cmd>	stack trace, exit 1	envelope, exit 66
session close <bad-id>	stack trace, exit 1	envelope, exit 2

$ webcmd adapter path hackernews/top
ok: false
error:
code: ARGUMENT
message: Adapter source is unavailable for hackernews/top.
exitCode: 2
$ webcmd session close bogus
ok: false
error:
code: INVALID_SESSION_SELECTOR
message: 'Session selector must be an opaque Session ID: bogus'
help: Run `webcmd session create` and pass the returned `session_...` ID.
exitCode: 2

Same envelope adapters already emit, on stderr, so an agent parses built-in and adapter failures the same way. Exit codes now come from the error instead of being lost, which finally applies the taxonomy already declared in errors.ts — site fixture get on a missing fixture exits 66 (EMPTY_RESULT), not 1.

Stacks stay off unless WEBCMD_DEBUG is set.

Reuse, not new machinery

toEnvelope() (errors.ts) and formatErrorEnvelope() (output.ts) already existed and are what commanderAdapter.ts uses for adapter errors. reportCliError just wires them to the built-in path; it takes an injectable stream so it is directly testable.

Two consequences worth reviewing

parse() → parseAsync(), and main.ts awaits. This is what lets an async rejection reach the handler at all.

Signal cancellation now covers the actual run.parse() returned as soon as it kicked off an async action, so main.ts's finally { uninstallSignalCancellation() } tore down the SIGINT handler while the run was still in flight — Ctrl-C during an adapter run never cancelled the daemon run. Awaiting keeps it installed for the real duration. This is a behaviour fix that falls out of the same change; calling it out because it is not obvious from the diff.

Verification

• npm run typecheck — clean
• npm test — 5687 passed, 1 failed: src/doctor.test.ts:218 (profile alias rendering), pre-existing on main, unrelated
• All five commands above exercised against a local build; exit codes confirmed with $?
• Happy paths re-checked (hackernews top, list, --help) — still exit 0
• New src/cli-error-report.test.ts covers the envelope, the hint, the UNKNOWN fallback, and the WEBCMD_DEBUG stack toggle

Tests went in a new file rather than cli.test.ts so this branch and #361 stay conflict-free.

Not in this PR

adapter path still fails for every command that is not already a local override (finding #2) — that is a separate bug in resolveAdapterSourcePath. This PR makes it report the failure properly instead of crashing; it does not make the command work.

🤖 Generated with Claude Code

[github-actions]

🟠 Maintainer review suggested — low confidence

The automated review could not reach a fully supported conclusion.

Limitations

• The automated review returned an invalid structured result.

This review is advisory and does not block merging.

[ankitranjan7]

Finding #1 from the CLI audit. Independent of #361 — branched from main, no overlapping hunks.

The bug

runCli was createProgram(...).parse() with no error handling. Anything a built-in command threw escaped: sync throws printed a raw Node stack trace, async ones surfaced as unhandled rejections, and either way the exitCode the error carried was thrown away.

$ webcmd adapter path hackernews/top
file:///…/dist/src/cli.js:1635
throw new ArgumentError(`Adapter source is unavailable …`);
^
ArgumentError: Adapter source is unavailable for hackernews/top.
at localAdapterPath (file:///…/dist/src/cli.js:1635:19)
…

Adapter commands never had this problem — execution.ts wraps them and renders the shared error envelope. Only built-ins were unprotected.

Five commands this fixes

command	before	after
adapter path <site>/<cmd>	stack trace, exit 1	envelope, exit 2
adapter source get <site>/<cmd>	stack trace, exit 1	envelope, exit 2
adapter source put <a>/<b> <path>	stack trace, exit 1	envelope, exit 2
site fixture get <site>/<cmd>	stack trace, exit 1	envelope, exit 66
session close <bad-id>	stack trace, exit 1	envelope, exit 2

$ webcmd adapter path hackernews/top
ok: false
error:
code: ARGUMENT
message: Adapter source is unavailable for hackernews/top.
exitCode: 2
$ webcmd session close bogus
ok: false
error:
code: INVALID_SESSION_SELECTOR
message: 'Session selector must be an opaque Session ID: bogus'
help: Run `webcmd session create` and pass the returned `session_...` ID.
exitCode: 2

Same envelope adapters already emit, on stderr, so an agent parses built-in and adapter failures the same way. Exit codes now come from the error instead of being lost, which finally applies the taxonomy already declared in errors.ts — site fixture get on a missing fixture exits 66 (EMPTY_RESULT), not 1.

Stacks stay off unless WEBCMD_DEBUG is set.

Reuse, not new machinery

toEnvelope() (errors.ts) and formatErrorEnvelope() (output.ts) already existed and are what commanderAdapter.ts uses for adapter errors. reportCliError just wires them to the built-in path; it takes an injectable stream so it is directly testable.

Two consequences worth reviewing

parse() → parseAsync(), and main.ts awaits. This is what lets an async rejection reach the handler at all.

Signal cancellation now covers the actual run.parse() returned as soon as it kicked off an async action, so main.ts's finally { uninstallSignalCancellation() } tore down the SIGINT handler while the run was still in flight — Ctrl-C during an adapter run never cancelled the daemon run. Awaiting keeps it installed for the real duration. This is a behaviour fix that falls out of the same change; calling it out because it is not obvious from the diff.

Verification

• npm run typecheck — clean
• npm test — 5687 passed, 1 failed: src/doctor.test.ts:218 (profile alias rendering), pre-existing on main, unrelated
• All five commands above exercised against a local build; exit codes confirmed with $?
• Happy paths re-checked (hackernews top, list, --help) — still exit 0
• New src/cli-error-report.test.ts covers the envelope, the hint, the UNKNOWN fallback, and the WEBCMD_DEBUG stack toggle

Tests went in a new file rather than cli.test.ts so this branch and #361 stay conflict-free.

Not in this PR

adapter path still fails for every command that is not already a local override (finding #2) — that is a separate bug in resolveAdapterSourcePath. This PR makes it report the failure properly instead of crashing; it does not make the command work.

🤖 Generated with Claude Code

[github-actions]

🟠 Maintainer review suggested — low confidence

The automated review could not reach a fully supported conclusion.

Limitations

• The automated review returned an invalid structured result.

This review is advisory and does not block merging.

[ankitranjan7]

Finding #1 from the CLI audit. Independent of #361 — branched from main, no overlapping hunks.

The bug

runCli was createProgram(...).parse() with no error handling. Anything a built-in command threw escaped: sync throws printed a raw Node stack trace, async ones surfaced as unhandled rejections, and either way the exitCode the error carried was thrown away.

$ webcmd adapter path hackernews/top
file:///…/dist/src/cli.js:1635
throw new ArgumentError(`Adapter source is unavailable …`);
^
ArgumentError: Adapter source is unavailable for hackernews/top.
at localAdapterPath (file:///…/dist/src/cli.js:1635:19)
…

Adapter commands never had this problem — execution.ts wraps them and renders the shared error envelope. Only built-ins were unprotected.

Five commands this fixes

command	before	after
adapter path <site>/<cmd>	stack trace, exit 1	envelope, exit 2
adapter source get <site>/<cmd>	stack trace, exit 1	envelope, exit 2
adapter source put <a>/<b> <path>	stack trace, exit 1	envelope, exit 2
site fixture get <site>/<cmd>	stack trace, exit 1	envelope, exit 66
session close <bad-id>	stack trace, exit 1	envelope, exit 2

$ webcmd adapter path hackernews/top
ok: false
error:
code: ARGUMENT
message: Adapter source is unavailable for hackernews/top.
exitCode: 2
$ webcmd session close bogus
ok: false
error:
code: INVALID_SESSION_SELECTOR
message: 'Session selector must be an opaque Session ID: bogus'
help: Run `webcmd session create` and pass the returned `session_...` ID.
exitCode: 2

Same envelope adapters already emit, on stderr, so an agent parses built-in and adapter failures the same way. Exit codes now come from the error instead of being lost, which finally applies the taxonomy already declared in errors.ts — site fixture get on a missing fixture exits 66 (EMPTY_RESULT), not 1.

Stacks stay off unless WEBCMD_DEBUG is set.

Reuse, not new machinery

toEnvelope() (errors.ts) and formatErrorEnvelope() (output.ts) already existed and are what commanderAdapter.ts uses for adapter errors. reportCliError just wires them to the built-in path; it takes an injectable stream so it is directly testable.

Two consequences worth reviewing

parse() → parseAsync(), and main.ts awaits. This is what lets an async rejection reach the handler at all.

Signal cancellation now covers the actual run.parse() returned as soon as it kicked off an async action, so main.ts's finally { uninstallSignalCancellation() } tore down the SIGINT handler while the run was still in flight — Ctrl-C during an adapter run never cancelled the daemon run. Awaiting keeps it installed for the real duration. This is a behaviour fix that falls out of the same change; calling it out because it is not obvious from the diff.

Verification

• npm run typecheck — clean
• npm test — 5687 passed, 1 failed: src/doctor.test.ts:218 (profile alias rendering), pre-existing on main, unrelated
• All five commands above exercised against a local build; exit codes confirmed with $?
• Happy paths re-checked (hackernews top, list, --help) — still exit 0
• New src/cli-error-report.test.ts covers the envelope, the hint, the UNKNOWN fallback, and the WEBCMD_DEBUG stack toggle

Tests went in a new file rather than cli.test.ts so this branch and #361 stay conflict-free.

Not in this PR

adapter path still fails for every command that is not already a local override (finding #2) — that is a separate bug in resolveAdapterSourcePath. This PR makes it report the failure properly instead of crashing; it does not make the command work.

🤖 Generated with Claude Code

[github-actions]

🟠 Maintainer review suggested — low confidence

The automated review could not reach a fully supported conclusion.

Limitations

• The automated review returned an invalid structured result.

This review is advisory and does not block merging.

[ankitranjan7]

Finding #1 from the CLI audit. Independent of #361 — branched from main, no overlapping hunks.

The bug

runCli was createProgram(...).parse() with no error handling. Anything a built-in command threw escaped: sync throws printed a raw Node stack trace, async ones surfaced as unhandled rejections, and either way the exitCode the error carried was thrown away.

$ webcmd adapter path hackernews/top
file:///…/dist/src/cli.js:1635
throw new ArgumentError(`Adapter source is unavailable …`);
^
ArgumentError: Adapter source is unavailable for hackernews/top.
at localAdapterPath (file:///…/dist/src/cli.js:1635:19)
…

Adapter commands never had this problem — execution.ts wraps them and renders the shared error envelope. Only built-ins were unprotected.

Five commands this fixes

command	before	after
adapter path <site>/<cmd>	stack trace, exit 1	envelope, exit 2
adapter source get <site>/<cmd>	stack trace, exit 1	envelope, exit 2
adapter source put <a>/<b> <path>	stack trace, exit 1	envelope, exit 2
site fixture get <site>/<cmd>	stack trace, exit 1	envelope, exit 66
session close <bad-id>	stack trace, exit 1	envelope, exit 2

$ webcmd adapter path hackernews/top
ok: false
error:
code: ARGUMENT
message: Adapter source is unavailable for hackernews/top.
exitCode: 2
$ webcmd session close bogus
ok: false
error:
code: INVALID_SESSION_SELECTOR
message: 'Session selector must be an opaque Session ID: bogus'
help: Run `webcmd session create` and pass the returned `session_...` ID.
exitCode: 2

Same envelope adapters already emit, on stderr, so an agent parses built-in and adapter failures the same way. Exit codes now come from the error instead of being lost, which finally applies the taxonomy already declared in errors.ts — site fixture get on a missing fixture exits 66 (EMPTY_RESULT), not 1.

Stacks stay off unless WEBCMD_DEBUG is set.

Reuse, not new machinery

toEnvelope() (errors.ts) and formatErrorEnvelope() (output.ts) already existed and are what commanderAdapter.ts uses for adapter errors. reportCliError just wires them to the built-in path; it takes an injectable stream so it is directly testable.

Two consequences worth reviewing

parse() → parseAsync(), and main.ts awaits. This is what lets an async rejection reach the handler at all.

Signal cancellation now covers the actual run.parse() returned as soon as it kicked off an async action, so main.ts's finally { uninstallSignalCancellation() } tore down the SIGINT handler while the run was still in flight — Ctrl-C during an adapter run never cancelled the daemon run. Awaiting keeps it installed for the real duration. This is a behaviour fix that falls out of the same change; calling it out because it is not obvious from the diff.

Verification

• npm run typecheck — clean
• npm test — 5687 passed, 1 failed: src/doctor.test.ts:218 (profile alias rendering), pre-existing on main, unrelated
• All five commands above exercised against a local build; exit codes confirmed with $?
• Happy paths re-checked (hackernews top, list, --help) — still exit 0
• New src/cli-error-report.test.ts covers the envelope, the hint, the UNKNOWN fallback, and the WEBCMD_DEBUG stack toggle

Tests went in a new file rather than cli.test.ts so this branch and #361 stay conflict-free.

Not in this PR

adapter path still fails for every command that is not already a local override (finding #2) — that is a separate bug in resolveAdapterSourcePath. This PR makes it report the failure properly instead of crashing; it does not make the command work.

🤖 Generated with Claude Code

[github-actions]

🟠 Maintainer review suggested — low confidence

The automated review could not reach a fully supported conclusion.

Limitations

• The automated review returned an invalid structured result.

This review is advisory and does not block merging.