fix: surface TOC extraction failures instead of writing a partial toc…

[MuhammadRafay1]

The issue

portal toc new treated every failure to extract endpoint data as a reason to fall back to the default TOC:

if (result.isErr()) {
  this.prompts.fallingBackToDefault();
  return TocComponents.empty();
}

TocComponents.empty() means "no Endpoints, Events or Models sections". So when a user was logged out — or hit a network error, an expired key, or an invalid spec — the command would:

1. Write a toc.yml containing only custom content, overwriting a possibly valid existing TOC,
2. Report success, giving no indication that the endpoint sections were dropped, and
3. Hang instead of returning to the shell.

The hang had a separate cause. generateTocData is a callAsStream endpoint, so on failure the SDK hands back an undrained IncomingMessage on ApiError.body. Its socket stays open and keeps the Node event loop alive, and since outro() only sets process.exitCode — we never call process.exit() — the process printed its outro and then sat there.

The fix

1. Propagate the error instead of silently degrading

actions/portal/toc/new-toc.ts

The inner IIFE now returns Result<TocComponents, ServiceError>. A failed extraction returns err(...); the caller reports the reason (auth, network, invalid spec) and returns ActionResult.failed(), leaving toc.yml untouched.

The genuinely-expected case is preserved: no spec/ directory still falls back to the default TOC, because there is nothing to extract and the default is the correct output. Only a failed extraction is now fatal. specFileStream.close() moved into a finally so it is released on both paths.

2. Release stream error bodies

infrastructure/service-error.ts

New exported discardStreamBody(error), called from handleServiceError after mapApiError has run, so mapping still reads error.result. Non-stream bodies are strings or Blobs with no destroy, so the check is typeof body?.destroy === "function".

Applied in the two services that catch ApiError without routing through handleServiceError:

• transformation-service.ts — in a finally, so the 401 branch can still JSON.parse the body before it is discarded.
• validation-service.ts — before the switch, since no branch there reads the body.

PortalService.generatePortal's 422 path is deliberately untouched: it returns error.body as the validation report at portal-service.ts:110-111, short-circuiting before handleServiceError, so that stream is never destroyed.

3. Renamed prompt method

PortalNewTocPrompts.logError → tocExtractionFailed, to name what it reports.

Behavior change

portal toc new now fails rather than writing a partial TOC when endpoint extraction fails — including when the user is logged out. Previously it exited 0 with a degraded file. PortalNewTocAction is only used by commands/portal/toc/new.ts, so nothing else is affected.

[mehnoorsiddiqui]

Unguarded JSON.parse on an Error Path

The following line performs an unguarded JSON parse on an error path:

const message = JSON.parse(apiError.body as string).message;

There are three common scenarios where this throws:

Input	Result
Stream body (401 from downloadTransformedFile, a callAsStream endpoint)	JSON.parse stringifies the IncomingMessage to "[object Object]" → SyntaxError (confirmed)
Empty body	JSON.parse("") → SyntaxError
Non-JSON body (gateway/proxy HTML, e.g. a corporate MITM 401 page)	SyntaxError

The third case is the realistic one. Enterprise users behind an authenticating proxy often receive an HTML error page instead of JSON.

Consequence

The SyntaxError escapes handleTransformationErrors, then escapes the catch block in transformViaFile (because the throw occurs inside err(await this.handleTransformationErrors(error))), and ultimately surfaces as an unhandled rejection.

As a result:

• Users receive a raw stack trace instead of the intended error message.
• outro(result) is skipped.
• The process exits with the wrong exit code.
• Failure telemetry is not recorded correctly.

Severity

Medium — this does not cause data loss or corruption, but it degrades an already-failing path into an unhandled exception and breaks expected error reporting.

Why This Belongs in This PR

Although this issue is pre-existing, this PR modifies these exact lines by wrapping them in try/finally and adds a comment asserting that this branch safely reads the body.

Additionally:

• The safe-parse pattern already exists in the sibling file (validation-service.ts, lines 225–234).
• unauthorizedWithHint already accepts string | null.

This is a small, low-risk fix (roughly five lines) that aligns this code path with the existing implementation.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud