feat(app-admin): AI mode in the command palette

ai-context/code-style/README.md

@@ -4,26 +4,27 @@ One rule per file. Each file states a single convention in `Do this / don't do t
 
 Read every rule in this folder before writing or editing code.
 
-| Rule                                                                                                   | Summary                                                                                |
-| ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
-| [comments.md](./comments.md)                                                                           | `//` single-line, `/* */` multi-line, end with a period.                               |
-| [es-modules.md](./es-modules.md)                                                                       | Use `import`/`export`, not CommonJS `require`.                                         |
-| [one-import-per-line.md](./one-import-per-line.md)                                                     | Only one named import per line.                                                        |
-| [one-class-per-file.md](./one-class-per-file.md)                                                       | One file MUST contain only one class.                                                  |
-| [no-backwards-compat.md](./no-backwards-compat.md)                                                     | Refactors ignore backwards compatibility unless the prompt says otherwise.             |
-| [no-console-in-backend.md](./no-console-in-backend.md)                                                 | No `console.*` in `api-*` code; use the DI `Logger`.                                   |
-| [no-inline-class-in-create-implementation.md](./no-inline-class-in-create-implementation.md)           | Declare implementation classes separately with an `implements` clause.                 |
-| [compose-css-class-names.md](./compose-css-class-names.md)                                             | Compose class names with a `cn` helper, never `+` or template literals.                |
-| [no-inline-conditional-spreads.md](./no-inline-conditional-spreads.md)                                 | Build objects with `if` statements, not inline conditional spreads/casts.              |
-| [no-nested-call-arguments.md](./no-nested-call-arguments.md)                                           | Name each step; don't nest calls as arguments to other calls.                          |
-| [one-public-function-per-file.md](./one-public-function-per-file.md)                                   | One exported function per file; composition steps always get their own.                |
-| [prefer-type-annotation-over-cast.md](./prefer-type-annotation-over-cast.md)                           | Annotate the variable; never add parens just to cast an expression.                    |
-| [no-container-as-service-locator.md](./no-container-as-service-locator.md)                             | Declare dependencies; don't inject a Container and resolve inside methods.             |
-| [no-stateless-private-methods.md](./no-stateless-private-methods.md)                                   | A private method that never reads `this` becomes a module-level function.              |
-| [presenter-owns-component-state.md](./presenter-owns-component-state.md)                               | Non-trivial component state goes in a presenter, reached via `useFeature`.             |
-| [no-multiline-ternaries.md](./no-multiline-ternaries.md)                                               | Ternaries stay on one line; wrapping or nested ones become `if` statements.            |
-| [prefer-provider-over-resolved-value.md](./prefer-provider-over-resolved-value.md)                     | Inject a provider with `get()`; never an abstraction holding another's result.         |
-| [check-the-layer-below-before-caching.md](./check-the-layer-below-before-caching.md)                   | Check whether the layer below already caches; memoizing providers go per request.      |
-| [without-authorization-only-for-private-models.md](./without-authorization-only-for-private-models.md) | `withoutAuthorization` is a no-op on private models; keep it where reads are filtered. |
+| Rule                                                                                                   | Summary                                                                                 |
+| ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
+| [comments.md](./comments.md)                                                                           | `//` single-line, `/* */` multi-line, end with a period.                                |
+| [es-modules.md](./es-modules.md)                                                                       | Use `import`/`export`, not CommonJS `require`.                                          |
+| [one-import-per-line.md](./one-import-per-line.md)                                                     | Only one named import per line.                                                         |
+| [one-class-per-file.md](./one-class-per-file.md)                                                       | One file MUST contain only one class; a route and its definition are the one exception. |
+| [no-backwards-compat.md](./no-backwards-compat.md)                                                     | Refactors ignore backwards compatibility unless the prompt says otherwise.              |
+| [no-console-in-backend.md](./no-console-in-backend.md)                                                 | No `console.*` in `api-*` code; use the DI `Logger`.                                    |
+| [no-inline-class-in-create-implementation.md](./no-inline-class-in-create-implementation.md)           | Declare implementation classes separately with an `implements` clause.                  |
+| [compose-css-class-names.md](./compose-css-class-names.md)                                             | Compose class names with a `cn` helper, never `+` or template literals.                 |
+| [no-inline-conditional-spreads.md](./no-inline-conditional-spreads.md)                                 | Build objects with `if` statements, not inline conditional spreads/casts.               |
+| [no-nested-call-arguments.md](./no-nested-call-arguments.md)                                           | Name each step; don't nest calls as arguments to other calls.                           |
+| [one-public-function-per-file.md](./one-public-function-per-file.md)                                   | One exported function per file; composition steps always get their own.                 |
+| [prefer-type-annotation-over-cast.md](./prefer-type-annotation-over-cast.md)                           | Annotate the variable; never add parens just to cast an expression.                     |
+| [no-container-as-service-locator.md](./no-container-as-service-locator.md)                             | Declare dependencies; don't inject a Container and resolve inside methods.              |
+| [no-stateless-private-methods.md](./no-stateless-private-methods.md)                                   | A private method that never reads `this` becomes a module-level function.               |
+| [presenter-owns-component-state.md](./presenter-owns-component-state.md)                               | Non-trivial component state goes in a presenter, reached via `useFeature`.              |
+| [no-multiline-ternaries.md](./no-multiline-ternaries.md)                                               | Ternaries stay on one line; wrapping or nested ones become `if` statements.             |
+| [routes-delegate-to-use-cases.md](./routes-delegate-to-use-cases.md)                                   | Routes parse and map; feature logic lives in a use case.                                |
+| [prefer-provider-over-resolved-value.md](./prefer-provider-over-resolved-value.md)                     | Inject a provider with `get()`; never an abstraction holding another's result.          |
+| [check-the-layer-below-before-caching.md](./check-the-layer-below-before-caching.md)                   | Check whether the layer below already caches; memoizing providers go per request.       |
+| [without-authorization-only-for-private-models.md](./without-authorization-only-for-private-models.md) | `withoutAuthorization` is a no-op on private models; keep it where reads are filtered.  |
 
 When adding a new code-style rule, create a new `*.md` file here (one rule per file) and add it to the table above.

ai-context/code-style/one-class-per-file.md

@@ -12,3 +12,43 @@ export class Foo {}
 export class Foo {}
 export class Bar {} // move to Bar.ts
 ```
+
+## Exception: an HTTP route and its definition
+
+A route is two classes that exist only as a pair, and they belong in one file.
+
+`HttpRouteDefinition` carries the method, the path and a reference to the handler. It takes no
+dependencies, so the router can build every definition and match a request without constructing any
+handler. `HttpRouteHandler` takes the dependencies and runs only once a request reaches that path.
+
+Splitting them across two files buys nothing: neither is usable or testable without the other, and
+the definition's only content is three fields naming the handler beside it. Keeping them together
+also keeps the path next to the code that serves it.
+
+```ts
+// Good: AiChatStreamRoute.ts
+class AiChatStreamRouteImpl implements HttpRouteHandler.Interface {
+  constructor(private readonly aiChat: AiChatUseCase.Interface) {}
+  async handle(request: IHttpRequest, response: IHttpResponseBuilder) {
+    /* ... */
+  }
+}
+
+export const AiChatStreamRoute = HttpRouteHandler.createImplementation({
+  implementation: AiChatStreamRouteImpl,
+  dependencies: [AiChatUseCase]
+});
+
+class AiChatStreamRouteDefinitionImpl implements HttpRouteDefinition.Interface {
+  readonly method = "POST";
+  readonly path = "/stream/ai/chat";
+  readonly handler = AiChatStreamRoute;
+}
+
+export const AiChatStreamRouteDefinition = HttpRouteDefinition.createImplementation({
+  implementation: AiChatStreamRouteDefinitionImpl,
+  dependencies: []
+});
+```
+
+Only the definition is registered with the container. The router resolves the handler it names.

ai-context/code-style/routes-delegate-to-use-cases.md

@@ -0,0 +1,40 @@
+# Routes Delegate To Use Cases
+
+An `HttpRoute` is transport, not feature code. Its job is to parse the request, call one use case, and
+map the outcome onto a status code. Business logic — auth checks, orchestration, calls to other
+services — belongs in a use case behind its own abstraction, so it can be resolved, decorated and
+tested without an HTTP request.
+
+```ts
+// Good
+class CreateThingRouteImpl implements HttpRoute.Interface {
+  public readonly method = "POST";
+  public readonly path = "/things";
+
+  public constructor(private readonly createThing: CreateThingUseCase.Interface) {}
+
+  public async handle(request: IHttpRequest): Promise<IHttpResponse> {
+    const params = parseBody(request.body);
+    if (!params) {
+      return json(400, { error: "Invalid body." });
+    }
+    return json(200, await this.createThing.execute(params));
+  }
+}
+```
+
+```ts
+// Bad — the feature lives in the route, so nothing else can reuse or test it
+class CreateThingRouteImpl implements HttpRoute.Interface {
+  public async handle(request: IHttpRequest): Promise<IHttpResponse> {
+    const identity = this.identityContext.getIdentity();
+    if (identity.isAnonymous()) {
+      return json(401, { error: "Authentication required." });
+    }
+    const validated = validate(request.body);
+    const created = await this.repository.create(validated);
+    await this.eventPublisher.publish(new ThingCreatedEvent(created));
+    return json(200, created);
+  }
+}
+```

packages/admin-ui/src/Markdown/Markdown.tsx

@@ -0,0 +1,53 @@
+import React from "react";
+import { cn, makeDecoratable } from "~/utils.js";
+import { Text, type TextProps } from "~/Text/index.js";
+import { useAdminUi } from "~/AdminUiProvider/index.js";
+
+/**
+ * Styling for compiled markdown BLOCKS.
+ *
+ * Tailwind's preflight strips list markers and paragraph margins, and the markdown compiler emits
+ * bare elements, so without this a list renders as unindented run-on text and a fenced code block as
+ * plain prose. Child selectors rather than a global stylesheet, so this reaches only markdown that
+ * was asked to be styled.
+ *
+ * Exported for a caller that needs the classes without this component, e.g. one already rendering
+ * compiled markdown inside its own element.
+ */
+export const markdownBlockClasses = [
+    "[&_p]:mb-xs [&_p:last-child]:mb-0",
+    "[&_ul]:mb-xs [&_ul]:list-disc [&_ul]:pl-lg",
+    "[&_ol]:mb-xs [&_ol]:list-decimal [&_ol]:pl-lg",
+    "[&_li]:mt-xxs",
+    "[&_strong]:font-semibold",
+    "[&_a]:underline",
+    "[&_code]:rounded [&_code]:bg-neutral-subtle [&_code]:px-xs [&_code]:font-mono",
+    "[&_pre]:mb-xs [&_pre]:overflow-x-auto [&_pre]:rounded [&_pre]:bg-neutral-subtle [&_pre]:p-sm"
+].join(" ");
+
+export interface MarkdownProps extends Pick<TextProps, "size" | "className"> {
+    children: React.ReactNode;
+}
+
+/**
+ * Renders markdown that contains block content: paragraphs, lists, fenced code.
+ *
+ * `Alert`, `Label` and the form-field descriptions call `compileMarkdown` directly and need none of
+ * this, because they render a sentence with a bold word or a link. Reach for this component when the
+ * source is long-form and its structure has to survive.
+ *
+ * Renders a `div`, since `Text` is a span by default and block markdown nested in one is invalid.
+ */
+const MarkdownBase = ({ children, size = "sm", className }: MarkdownProps) => {
+    const { compileMarkdown } = useAdminUi();
+
+    return (
+        <Text as="div" size={size} className={cn(markdownBlockClasses, className)}>
+            {compileMarkdown(children)}
+        </Text>
+    );
+};
+
+const Markdown = makeDecoratable("Markdown", MarkdownBase);
+
+export { Markdown };

packages/admin-ui/src/Markdown/index.ts

@@ -0,0 +1 @@
+export * from "./Markdown.js";

packages/admin-ui/src/index.ts

@@ -61,6 +61,7 @@ export * from "./Table/index.js";
 export * from "./Tabs/index.js";
 export * from "./Tag/index.js";
 export * from "./Tags/index.js";
+export * from "./Markdown/index.js";
 export * from "./Text/index.js";
 export * from "./Textarea/index.js";
 export * from "./Toggle/index.js";

packages/ai-chat/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@webiny/ai-chat",
+  "version": "0.0.0",
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./*": "./*"
+  },
+  "description": "AI assistant that answers questions about a Webiny project using its registered AI tools",
+  "keywords": [
+    "ai-chat:base"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/webiny/webiny-js.git",
+    "directory": "packages/ai-chat"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@webiny/api-core": "0.0.0",
+    "@webiny/event-handler-core": "0.0.0",
+    "@webiny/feature": "0.0.0",
+    "ai": "^7.0.73"
+  },
+  "devDependencies": {
+    "@webiny/build-tools": "0.0.0",
+    "@webiny/di": "^1.0.2",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "webiny": {
+    "publishFrom": "dist"
+  }
+}

packages/ai-chat/src/api/AiChatFeature.ts

@@ -0,0 +1,39 @@
+import { createFeature } from "@webiny/feature/api";
+import { AiChatConfig } from "./abstractions.js";
+import { AiChatUseCase } from "./AiChatUseCase.js";
+import { EnvAiChatProvider } from "./EnvAiChatProvider.js";
+import { AiChatStreamRouteDefinition } from "./AiChatStreamRoute.js";
+
+/**
+ * Enough steps for the deepest expected chain: list models, describe one, query it, answer — plus room
+ * for a corrected retry after a rejected filter.
+ */
+const DEFAULT_MAX_STEPS = 12;
+
+/**
+ * The AI chat feature: the use case, its configuration, and the HTTP route that reaches it.
+ *
+ * Routes live beside the use case rather than in a separate package, matching `AiImageEnrichment`.
+ * The assistant is only ever reached over HTTP, so a second package bought an indirection nobody
+ * used and one more manifest to keep in sync.
+ */
+export const AiChatFeature = createFeature({
+    name: "AiChat",
+    register: container => {
+        container.registerInstance(AiChatConfig, {
+            maxSteps: Number(process.env["WEBINY_API_AI_CHAT_MAX_STEPS"]) || DEFAULT_MAX_STEPS
+        });
+        /*
+         * Registered first so a later registration wins. AI Power-Ups overrides this with providers
+         * configured in the admin UI.
+         */
+        container.register(EnvAiChatProvider);
+        container.register(AiChatUseCase);
+
+        /*
+         * Only the definition is registered: the router matches on it and builds the handler it
+         * names once a request actually hits the path.
+         */
+        container.register(AiChatStreamRouteDefinition);
+    }
+});

packages/ai-chat/src/api/AiChatStreamRoute.ts

@@ -0,0 +1,72 @@
+import { HttpRouteDefinition, HttpRouteHandler, toSseFrame } from "@webiny/event-handler-core";
+import type { IHttpRequest, IHttpResponseBuilder } from "@webiny/event-handler-core";
+import { AiChatUseCase } from "./abstractions.js";
+import type { AiChatEvent } from "./events.js";
+import { parseChatBody } from "./parseChatBody.js";
+
+const BAD_REQUEST_MESSAGE =
+    "Provide either a non-empty `prompt` string or a `messages` array of model messages.";
+
+/**
+ * Frame the feature's events as SSE records. The wire format comes from `event-handler-core`; which
+ * events exist, and what they carry, belongs to the feature, so the mapping lives here.
+ */
+async function* toSseFrames(events: AsyncIterable<AiChatEvent>): AsyncIterable<string> {
+    for await (const event of events) {
+        yield toSseFrame(event);
+    }
+}
+
+/**
+ * `POST /stream/ai/chat`, the same assistant as `/ai/chat` but reported as it works.
+ *
+ * A separate route rather than a flag on the buffered one: the two have genuinely different response
+ * contracts (one JSON object versus an event stream), so a client picks which it wants by the URL it
+ * calls, and the buffered route stays available for callers that cannot read a stream.
+ *
+ * Failures after the first byte cannot become a status code, since the response has already committed
+ * to 200, so the use case reports them as `error` events and the stream ends normally.
+ */
+class AiChatStreamRouteImpl implements HttpRouteHandler.Interface {
+    public constructor(private readonly aiChat: AiChatUseCase.Interface) {}
+
+    public async handle(
+        request: IHttpRequest,
+        response: IHttpResponseBuilder
+    ): Promise<IHttpResponseBuilder> {
+        const parsed = parseChatBody(request.body);
+
+        if (!parsed) {
+            return response.status(400).json({ error: BAD_REQUEST_MESSAGE });
+        }
+
+        const events = this.aiChat.stream(parsed);
+        const frames = toSseFrames(events);
+
+        return response.sse(frames);
+    }
+}
+
+export const AiChatStreamRoute = HttpRouteHandler.createImplementation({
+    implementation: AiChatStreamRouteImpl,
+    dependencies: [AiChatUseCase]
+});
+
+class AiChatStreamRouteDefinitionImpl implements HttpRouteDefinition.Interface {
+    readonly name = "ai-chat-stream";
+    readonly method = "POST";
+    /*
+     * Under `/stream/*` because that prefix is what reaches a transport able to stream. On AWS,
+     * CloudFront routes `/stream/*` to the Lambda Function URL origin; everything else goes to API
+     * Gateway, which buffers the whole response no matter how the route produced it. A path outside
+     * this prefix still works, it just silently arrives all at once.
+     */
+    readonly path = "/stream/ai/chat";
+    readonly handler = AiChatStreamRoute;
+}
+
+/** What the router matches on. Zero dependencies, so building it costs nothing. */
+export const AiChatStreamRouteDefinition = HttpRouteDefinition.createImplementation({
+    implementation: AiChatStreamRouteDefinitionImpl,
+    dependencies: []
+});