@krak-stack/registry 0.1.37 → 0.1.39

package/README.md

@@ -52,12 +52,9 @@ import { Pagination } from "@krak-stack/registry/pagination";
 import { AgentService } from "@krak-stack/registry/agent";
 import { AgentWidget, makeAgentAtoms } from "@krak-stack/registry/agent/client";
 import { makeAgentApiGroup } from "@krak-stack/registry/agent/schema";
-import {
-  HttpApiToolkit,
-  HttpApiToolkitLayer,
-} from "@krak-stack/registry/httpapi-toolkit";
-import { ApiClient } from "@krak-stack/registry/httpapi/client";
-import { HttpApiSpec } from "@krak-stack/registry/httpapi/helpers";
+import { makeHttpApiToolkit } from "@krak-stack/registry/httpapi/toolkit";
+import { makeHttpApiCli } from "@krak-stack/registry/httpapi/cli";
+import { HttpApiAdapter } from "@krak-stack/registry/httpapi/adapter";
 import { HttpApiOtlp } from "@krak-stack/registry/opentelemetry/api";
 import { BrowserOtlp } from "@krak-stack/registry/opentelemetry/browser";
 import { createDocsSource, makeDocs } from "@krak-stack/registry/docs";
@@ -129,10 +126,137 @@ const siteSeo = createSeo({
 
 The returned object contains `meta`, `links`, and derived JSON-LD `scripts`. Website pages receive `WebSite` and `Organization` data; documentation pages can pass `type: "article"` for `Article` data. Use the lower-level `seo` function directly when a configured factory is not useful.
 
-HTTP API client, schema, AI tool, CLI, and MCP utilities are available under
+HTTP API adapter, AI tool, and CLI utilities are available under
 the `@krak-stack/registry/httpapi/*` subpaths. Keep application-specific API
 layers, handlers, authentication, and client bindings in the application.
 
+Use `@krak-stack/registry/httpapi/toolkit` for HTTP API tools.
+
+### HTTP API tools and MCP
+
+Static toolkits keep definitions and implementations separate:
+`DocumentationToolkit` / `DocumentationToolkitLayer({ docs, locale })` and
+`WebFetchToolkit` / `WebFetchToolkitLayer(options?)`. Merge the definitions with
+`Toolkit.merge`, then provide their handler layers. Web-fetch options are
+validated during layer acquisition through the Effect error channel.
+
+HTTP API tools are generated dynamically, so `makeHttpApiToolkit()` returns
+matching definitions and handlers together.
+
+CLI, toolkit, and MCP registration share `HttpApiAdapter.operations`. Each operation
+contains its tool name, typed `inputSchema`, derived `inputJsonSchema`, and method
+annotations. Inputs use `{ params, query, headers, body }`; only the CLI turns
+terminal arguments into that shape. The generated HTTP client handles wire
+encoding, and payload codecs retain their transformations.
+
+Use `makeHttpApiToolkit(config)` to construct matching tools and handlers once:
+
+```ts
+import { makeHttpApiToolkit } from "@krak-stack/registry/httpapi/toolkit";
+
+const { toolkit, handlers } = yield * makeHttpApiToolkit();
+const tools = yield * toolkit.pipe(Effect.provide(handlers));
+```
+
+Provide one `HttpApiAdapter` layer through the surrounding Effect layers:
+
+```ts
+const adapterLayer = HttpApiAdapter.layer({
+  api: AppApi,
+  baseUrl: "https://example.com",
+  methods: ["get"],
+}).pipe(Layer.provide(FetchHttpClient.layer));
+```
+
+This replaces the separate `HttpApiSpec` and `ApiClient` services. The catalogue,
+input/success codecs, execution client, and result encoder all use the same API.
+Import from `@krak-stack/registry/httpapi/adapter`, or install
+`@krak-stack/httpapi-adapter` with shadcn. The old client/helper package subpaths
+and client registry item have been removed.
+Configuration is optional. Construct once and use the returned pair for agents
+or MCP; the separate `HttpApiToolkit` and `HttpApiToolkitLayer` factories have
+been removed.
+
+For CLI commands, `makeHttpApiCli()` returns `{ command, run }`. Provide the same
+`HttpApiAdapter` layer and supply the platform CLI services when
+running commands. `run` derives the CLI version from the API metadata:
+
+```ts
+const { command, run } = yield * makeHttpApiCli();
+yield * run(args);
+```
+
+`makeHttpApiCli` is the only public CLI export. `HttpApiCli`, its layer, and the
+custom runners have been removed. Process arguments, platform services, error
+reporting, and exit handling belong to the application's Effect runtime:
+
+```ts
+import { NodeRuntime, NodeServices } from "@effect/platform-node";
+
+Effect.gen(function* () {
+  const { run } = yield* makeHttpApiCli();
+  yield* run(process.argv.slice(2));
+}).pipe(
+  Effect.provide(adapterLayer),
+  Effect.provide(NodeServices.layer),
+  NodeRuntime.runMain,
+);
+```
+
+Install `@effect/platform-node` matching your Effect version for this example;
+`adapterLayer` supplies the application's `HttpApiAdapter`.
+
+For an HTTP MCP server, register the toolkit directly with Effect. Keep the
+transport and server identity in the application:
+
+```ts
+import { Effect, Layer } from "effect";
+import { McpProtocol, McpServer } from "effect/ai";
+import { FetchHttpClient } from "effect/http";
+import { HttpApiAdapter } from "@krak-stack/registry/httpapi/adapter";
+import { makeHttpApiToolkit } from "@krak-stack/registry/httpapi/toolkit";
+import { AppApi } from "@/api";
+
+export const mcpLayer = Layer.effectDiscard(
+  Effect.gen(function* () {
+    const { toolkit, handlers } = yield* makeHttpApiToolkit({});
+    yield* McpServer.registerToolkit(toolkit).pipe(Effect.provide(handlers));
+  }),
+).pipe(
+  Layer.provideMerge(
+    McpServer.layerHttp({
+      name: "app",
+      version: "1.0.0",
+      path: "/api/mcp",
+      protocols: [McpProtocol.v2025_11_25],
+    }),
+  ),
+  Layer.provide(
+    HttpApiAdapter.layer({
+      api: AppApi,
+      baseUrl: "http://localhost:3000",
+      methods: ["get"],
+    }),
+  ),
+  Layer.provide(FetchHttpClient.layer),
+);
+```
+
+This example explicitly selects GET operations; `HttpApiAdapter` otherwise includes
+all supported methods. Use `include` to narrow exposure further. Supply an
+authenticated `HttpClient` instead of `FetchHttpClient.layer` when the downstream
+API requires credentials. Inbound MCP authentication and authorization remain
+application-owned; tool annotations are not access controls.
+
+If intentionally exposing writes, enforce authorization or confirmation in the
+application before opting out of agent approval with `needsApproval: () => false`.
+Approval requirements are no longer silently disabled by an MCP adapter.
+
+The `HttpApiMcp` service, `@krak-stack/registry/httpapi/mcp` export, and
+`@krak-stack/httpapi-mcp` registry item have been removed. Replace them with the
+composition above. Any Effect toolkit can be registered this way; it does not
+need to originate from an HttpApi.
+
 Documentation consumers load and compile their application-owned MDX on the
 server, then pass the validated page records to `createDocsSource` and
 `makeDocs`:

package/dist/components/ui/app-brand.js

@@ -53,38 +53,38 @@ function AppBrand(brandProps) {
   ].filter(Boolean).join(" ");
   if (isStaticBrand(brandProps)) {
     const {
-      className: _className2,
-      label: _label2,
-      subtitle: _subtitle2,
-      icon: _icon2,
-      imageSrc: _imageSrc2,
-      variant: _variant2,
+      className: _className,
+      label: _label,
+      subtitle: _subtitle,
+      icon: _icon,
+      imageSrc: _imageSrc,
+      variant: _variant,
       to: _to,
-      href: _href2,
-      ...props2
+      href: _href,
+      ...props
     } = brandProps;
     return /* @__PURE__ */ jsx("div", {
       className: brandClassName,
-      ...props2,
+      ...props,
       children: content
     });
   }
   if (isAnchorBrand(brandProps)) {
     const {
-      className: _className2,
-      label: _label2,
-      subtitle: _subtitle2,
-      icon: _icon2,
-      imageSrc: _imageSrc2,
-      variant: _variant2,
+      className: _className,
+      label: _label,
+      subtitle: _subtitle,
+      icon: _icon,
+      imageSrc: _imageSrc,
+      variant: _variant,
       to: _to,
       href,
-      ...props2
+      ...props
     } = brandProps;
     return /* @__PURE__ */ jsx("a", {
       className: brandClassName,
       href,
-      ...props2,
+      ...props,
       children: content
     });
   }

package/dist/components/ui/code-block.js

@@ -65,7 +65,7 @@ function CopyButton({
   valueDescription,
   copyVariant = "default",
   locale: localeOverride,
-  messages: messages2,
+  messages,
   onCopied,
   onCopyError,
   resetDelay = 1500,
@@ -77,7 +77,7 @@ function CopyButton({
   const locale = useKrakstackLocale(localeOverride);
   const [copyState, setCopyState] = useState("idle");
   const copyTimeout = useRef(undefined);
-  const labels = copyButtonMessages(locale, messages2);
+  const labels = copyButtonMessages(locale, messages);
   const accessibleLabel = ariaLabel ?? (valueDescription ? `${labels.copy} ${valueDescription}` : labels.copy);
   const isLarge = copyVariant === "large";
   const defaultSize = copyVariant === "sm" ? "icon-xs" : isLarge ? "sm" : "icon-sm";
@@ -179,12 +179,12 @@ function CodeBlock({
   code,
   language = "text",
   locale: localeOverride,
-  messages: messages3
+  messages
 }) {
   const locale = useKrakstackLocale2(localeOverride);
   const normalizedLanguage = language.toLowerCase() || "text";
   const highlighted = highlight(code, { lang: normalizedLanguage });
-  const labels = codeBlockMessages(locale, messages3);
+  const labels = codeBlockMessages(locale, messages);
   return /* @__PURE__ */ jsxs2("div", {
     className: "not-prose bg-muted overflow-hidden rounded-md border text-[var(--th-token)]",
     "data-code-theme": true,

package/dist/components/ui/copy-button.js

@@ -65,7 +65,7 @@ function CopyButton({
   valueDescription,
   copyVariant = "default",
   locale: localeOverride,
-  messages: messages2,
+  messages,
   onCopied,
   onCopyError,
   resetDelay = 1500,
@@ -77,7 +77,7 @@ function CopyButton({
   const locale = useKrakstackLocale(localeOverride);
   const [copyState, setCopyState] = useState("idle");
   const copyTimeout = useRef(undefined);
-  const labels = copyButtonMessages(locale, messages2);
+  const labels = copyButtonMessages(locale, messages);
   const accessibleLabel = ariaLabel ?? (valueDescription ? `${labels.copy} ${valueDescription}` : labels.copy);
   const isLarge = copyVariant === "large";
   const defaultSize = copyVariant === "sm" ? "icon-xs" : isLarge ? "sm" : "icon-sm";