feat: Improve error handling from 3P requests on interceptor

[atilafassina]

At the current state, the executor swallows external API errors in order to prevent the app from crashing.
While we still want to prevent the app from crashing, and these errors are not intended for user consumption, returning undefined from the interceptor means the plugins are unable to handle errors more gracefully and everything is looped as a server error.

In this change we still don't throw the error, and we implement a Result type, this way the integrated plugin always knows what shape to expect:

export type ExecutionResult<T> =
  | { ok: true; data: T }
  | { ok: false; status: number; message: string };

When it's an error, it will receive the real status code from the API and a message. With the status code, the plugin can then decide how to handle the error.

If a success, the actual payload is under data and is typed properly, just as it was in the previous type shape (Promise<T | undefined>)

[Copilot]

Pull request overview

This PR introduces a new ExecutionResult<T> return type for Plugin.execute() so plugins can handle failures without relying on undefined, and updates the Files plugin + generated docs to use the new discriminated union shape.

Changes:

• Added ExecutionResult<T> and changed Plugin.execute() to return { ok: true, data } | { ok: false, status, message } instead of T | undefined.
• Updated FilesPlugin handlers to branch on result.ok and return result.data on success.
• Updated unit tests and TypeDoc outputs to reflect the new API.

Reviewed changes

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

Show a summary per file

File	Description
packages/appkit/src/plugin/plugin.ts	Changes execute() contract to return ExecutionResult<T> and maps errors into { ok:false }.
packages/appkit/src/plugin/execution-result.ts	Introduces the ExecutionResult<T> type alias.
packages/appkit/src/plugin/index.ts	Re-exports ExecutionResult from the plugin module.
packages/appkit/src/index.ts	Re-exports ExecutionResult from the top-level AppKit API surface.
packages/appkit/src/plugins/files/plugin.ts	Updates route handlers to use result.ok / result.data instead of checking for undefined.
packages/appkit/src/plugin/tests/plugin.test.ts	Updates expectations for the new ExecutionResult shape and adds status mapping tests.
docs/docs/api/appkit/*	Updates generated TypeDoc pages/sidebar to include ExecutionResult and the updated Plugin.execute() signature/docs.
docs/static/appkit-ui/styles.gen.css	Generated CSS output changes (unrelated to execution result logic).

---

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