@assistant-ui/mcp-docs-server 0.2.3 → 0.3.0

package/.docs/organized/code-examples/with-react-ink.md

@@ -1,473 +0,0 @@
-# Example: with-react-ink
-
-## package.json
-
-```json
-{
-  "name": "with-react-ink",
-  "version": "0.0.0",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "dev": "node --import tsx/esm src/dev.ts",
-    "build": "tsc",
-    "start": "node dist/index.js"
-  },
-  "dependencies": {
-    "@assistant-ui/react-ink": "workspace:*",
-    "@assistant-ui/react-ink-markdown": "workspace:*",
-    "ink": "^7.1.1",
-    "react": "^19.2.8"
-  },
-  "devDependencies": {
-    "@types/react": "^19.2.18",
-    "esbuild": "^0.28.2",
-    "tsx": "^4.23.12",
-    "typescript": "^7.0.2"
-  }
-}
-
-```
-
-## src/app.tsx
-
-```tsx
-import { useMemo } from "react";
-import { Box, Text } from "ink";
-import {
-  AssistantRuntimeProvider,
-  AuiConfig,
-  useLocalRuntime,
-  StatusBarPrimitive,
-  Tools,
-} from "@assistant-ui/react-ink";
-import { Thread } from "./components/thread.js";
-import { createScriptedAdapter, MODEL_NAME } from "./scripted-adapter.js";
-import toolkit from "./tools.js";
-
-const StatusBar = () => (
-  <StatusBarPrimitive.Root>
-    <Text dimColor>
-      model: <StatusBarPrimitive.ModelName name={MODEL_NAME} /> ·{" "}
-      <StatusBarPrimitive.MessageCount /> · <StatusBarPrimitive.Status />
-    </Text>
-  </StatusBarPrimitive.Root>
-);
-
-export const App = () => {
-  const adapter = useMemo(() => createScriptedAdapter(), []);
-  const runtime = useLocalRuntime(adapter);
-  const config = AuiConfig({
-    tools: Tools({ toolkit }),
-  });
-
-  return (
-    <AssistantRuntimeProvider runtime={runtime} config={config}>
-      <Box flexDirection="column" padding={1}>
-        <Box>
-          <Text bold color="cyan">
-            demo-agent
-          </Text>
-          <Text dimColor>{"  ~/acme-app"}</Text>
-        </Box>
-        <StatusBar />
-        <Box marginTop={1}>
-          <Thread />
-        </Box>
-      </Box>
-    </AssistantRuntimeProvider>
-  );
-};
-
-```
-
-## src/components/thread.tsx
-
-```tsx
-import { Box, Text } from "ink";
-import {
-  AuiIf,
-  ThreadPrimitive,
-  ComposerPrimitive,
-  MessagePrimitive,
-  ErrorPrimitive,
-  LoadingPrimitive,
-  LiveChecklist,
-} from "@assistant-ui/react-ink";
-import { MarkdownText } from "@assistant-ui/react-ink-markdown";
-
-const UserMessage = () => (
-  <MessagePrimitive.Root>
-    <Box marginBottom={1}>
-      <Text bold color="green">
-        You:{" "}
-      </Text>
-      <MessagePrimitive.Content
-        renderText={({ part }) => <Text wrap="wrap">{part.text}</Text>}
-      />
-    </Box>
-  </MessagePrimitive.Root>
-);
-
-const AssistantMessage = () => (
-  <MessagePrimitive.Root>
-    <Box flexDirection="column" marginBottom={1}>
-      <Text bold color="blue">
-        AI:
-      </Text>
-      <MessagePrimitive.Content
-        renderText={({ part }) => <MarkdownText text={part.text} />}
-        renderReasoning={({ part }) => (
-          <Text dimColor italic>
-            {part.text}
-          </Text>
-        )}
-      />
-      <LiveChecklist title="Plan" showProgress marginTop={1} />
-      <ErrorPrimitive.Root>
-        <ErrorPrimitive.Message />
-      </ErrorPrimitive.Root>
-    </Box>
-  </MessagePrimitive.Root>
-);
-
-const Loading = () => (
-  <LoadingPrimitive.Root marginBottom={1}>
-    <LoadingPrimitive.Spinner />
-    <Text> </Text>
-    <LoadingPrimitive.Text>Working</LoadingPrimitive.Text>
-    <Text> </Text>
-    <LoadingPrimitive.ElapsedTime />
-  </LoadingPrimitive.Root>
-);
-
-export const Thread = () => {
-  return (
-    <ThreadPrimitive.Root>
-      <AuiIf condition={(s) => s.thread.isEmpty}>
-        <Box flexDirection="column" marginBottom={1}>
-          <Text>
-            Working in this project. <Text color="yellow">fetchUser()</Text> is
-            flaky in prod and has no retry logic.
-          </Text>
-          <Text dimColor>{'  try: "make fetchUser retry on failure"'}</Text>
-        </Box>
-      </AuiIf>
-
-      <ThreadPrimitive.Messages>
-        {({ message }) =>
-          message.role === "user" ? <UserMessage /> : <AssistantMessage />
-        }
-      </ThreadPrimitive.Messages>
-
-      <Loading />
-
-      <Box borderStyle="round" borderColor="gray" paddingX={1}>
-        <Text color="gray">{"> "}</Text>
-        <ComposerPrimitive.Input
-          submitOnEnter
-          multiLine
-          placeholder="Type a message... (Enter to send)"
-          autoFocus
-        />
-      </Box>
-    </ThreadPrimitive.Root>
-  );
-};
-
-```
-
-## src/dev.ts
-
-```typescript
-import { build } from "esbuild";
-import { spawn } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const outfile = join(__dirname, "..", ".dev", "index.mjs");
-
-await build({
-  entryPoints: [join(__dirname, "index.tsx")],
-  bundle: true,
-  platform: "node",
-  format: "esm",
-  outfile,
-  external: ["react", "react/*", "ink", "ink/*"],
-  jsx: "automatic",
-  jsxImportSource: "react",
-  logLevel: "warning",
-  ignoreAnnotations: true,
-});
-
-const child = spawn("node", [outfile], { stdio: "inherit" });
-child.on("exit", (code) => process.exit(code ?? 0));
-
-```
-
-## src/index.tsx
-
-```tsx
-import { render } from "ink";
-import { App } from "./app.js";
-
-render(<App />);
-
-```
-
-## src/scripted-adapter.ts
-
-```typescript
-import type {
-  ChatModelAdapter,
-  ThreadAssistantMessagePart,
-} from "@assistant-ui/react-ink";
-
-export const MODEL_NAME = "demo-agent";
-
-const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
-
-const RETRY_PATCH = `--- a/src/retry.ts
-+++ b/src/retry.ts
-@@ -1,6 +1,18 @@
- export async function fetchUser(id: string) {
--  const res = await fetch(\`/api/users/\${id}\`);
--  return res.json();
-+  return retry(() => fetch(\`/api/users/\${id}\`).then((r) => r.json()));
-+}
-+
-+export async function retry<T>(fn: () => Promise<T>, attempts = 3): Promise<T> {
-+  let lastError: unknown;
-+  for (let i = 0; i <= attempts; i++) {
-+    try {
-+      return await fn();
-+    } catch (err) {
-+      lastError = err;
-+      await new Promise((r) => setTimeout(r, 2 ** i * 100));
-+    }
-+  }
-+  throw lastError;
- }
-`;
-
-const RETRY_PATCH_FIX = `--- a/src/retry.ts
-+++ b/src/retry.ts
-@@ -6,7 +6,7 @@ export async function retry<T>(fn: () => Promise<T>, attempts = 3): Promise<T> {
-   let lastError: unknown;
--  for (let i = 0; i <= attempts; i++) {
-+  for (let i = 0; i < attempts; i++) {
-     try {
-       return await fn();
-     } catch (err) {
-`;
-
-const isTaskRequest = (text: string) =>
-  /fetch|retry|resilient|flaky|backoff|robust|network|\byes\b|sure|\bok\b|go ahead|do it|please/i.test(
-    text,
-  );
-
-const lastUserText = (
-  messages: readonly { role: string; content: readonly { type: string }[] }[],
-) => {
-  const last = messages.filter((m) => m.role === "user").at(-1);
-  return (
-    last?.content
-      .filter((p): p is { type: "text"; text: string } => p.type === "text")
-      .map((p) => p.text)
-      .join("") ?? ""
-  );
-};
-
-async function* streamText(
-  parts: ThreadAssistantMessagePart[],
-  index: number,
-  text: string,
-  delay: number,
-): AsyncGenerator<{ content: ThreadAssistantMessagePart[] }> {
-  for (const word of text.split(" ")) {
-    const p = parts[index] as Extract<
-      ThreadAssistantMessagePart,
-      { type: "text" | "reasoning" }
-    >;
-    parts[index] = { ...p, text: p.text ? `${p.text} ${word}` : word };
-    yield { content: [...parts] };
-    await sleep(delay);
-  }
-}
-
-async function* runAgentScript(): AsyncGenerator<{
-  content: ThreadAssistantMessagePart[];
-}> {
-  const parts: ThreadAssistantMessagePart[] = [];
-  const emit = () => ({ content: [...parts] });
-  const setResult = (result: unknown, isError = false) => {
-    parts[parts.length - 1] = {
-      ...parts[parts.length - 1],
-      result,
-      ...(isError ? { isError: true } : {}),
-    } as ThreadAssistantMessagePart;
-  };
-  const pushToolCall = (
-    toolCallId: string,
-    toolName: string,
-    args: Record<string, string>,
-  ) =>
-    parts.push({
-      type: "tool-call",
-      toolCallId,
-      toolName,
-      args,
-      argsText: JSON.stringify(args),
-    });
-
-  const reasoningIdx = parts.push({ type: "reasoning", text: "" }) - 1;
-  yield* streamText(
-    parts,
-    reasoningIdx,
-    "Let me look at how fetchUser is implemented, wrap it in retry-with-backoff, and run the tests to make sure it holds up.",
-    20,
-  );
-
-  pushToolCall("read-1", "read_file", { path: "src/retry.ts" });
-  yield emit();
-  await sleep(500);
-  setResult("12 lines read");
-  yield emit();
-  await sleep(300);
-
-  pushToolCall("patch-1", "apply_patch", {
-    path: "src/retry.ts",
-    patch: RETRY_PATCH,
-  });
-  yield emit();
-  await sleep(600);
-  setResult({ applied: true });
-  yield emit();
-  await sleep(300);
-
-  pushToolCall("test-1", "run_tests", { command: "pnpm test retry" });
-  yield emit();
-  await sleep(700);
-  setResult(
-    "FAIL src/retry.test.ts - retry() ran 4 times, expected 3 (off-by-one in loop bound)",
-    true,
-  );
-  yield emit();
-  await sleep(400);
-
-  const noteIdx = parts.push({ type: "text", text: "" }) - 1;
-  yield* streamText(
-    parts,
-    noteIdx,
-    "The loop bound was off by one. Tightening it and re-running.",
-    20,
-  );
-
-  pushToolCall("patch-2", "apply_patch", {
-    path: "src/retry.ts",
-    patch: RETRY_PATCH_FIX,
-  });
-  yield emit();
-  await sleep(500);
-  setResult({ applied: true });
-  yield emit();
-  await sleep(300);
-
-  pushToolCall("test-2", "run_tests", { command: "pnpm test retry" });
-  yield emit();
-  await sleep(600);
-  setResult("PASS src/retry.test.ts (3 passed)");
-  yield emit();
-  await sleep(300);
-
-  const summary = `### Done
-
-Added a \`retry()\` helper and routed \`fetchUser\` through it:
-
-- exponential backoff (\`100ms\`, \`200ms\`, \`400ms\`)
-- rethrows the **last error** after exhausting attempts
-- fixed an off-by-one that ran one extra attempt
-
-Tests are green.`;
-  const summaryIdx = parts.push({ type: "text", text: "" }) - 1;
-  yield* streamText(parts, summaryIdx, summary, 15);
-}
-
-async function* runProposalReply(): AsyncGenerator<{
-  content: ThreadAssistantMessagePart[];
-}> {
-  const response = `I'm set up to work in this repo. The obvious thing to fix is the flaky \`fetchUser()\` call in \`src/retry.ts\` — it has no retry logic, so a single network blip fails the request.
-
-Want me to wrap it in retry-with-backoff? Just say *make fetchUser retry on failure*.`;
-  let acc = "";
-  for (const word of response.split(" ")) {
-    acc += (acc ? " " : "") + word;
-    yield { content: [{ type: "text", text: acc }] };
-    await sleep(20);
-  }
-}
-
-export const createScriptedAdapter = (): ChatModelAdapter => ({
-  run({ messages }) {
-    return isTaskRequest(lastUserText(messages))
-      ? runAgentScript()
-      : runProposalReply();
-  },
-});
-
-```
-
-## src/tools.tsx
-
-```tsx
-import { Box, Text } from "ink";
-import {
-  defineToolkit,
-  DiffView,
-  type ToolCallMessagePartComponent,
-} from "@assistant-ui/react-ink";
-
-const ApplyPatchToolUI: ToolCallMessagePartComponent<
-  { path: string; patch: string },
-  unknown
-> = ({ args }) => {
-  if (!args?.patch) return null;
-  return (
-    <Box flexDirection="column" marginBottom={1}>
-      <Text color="cyan">edit {args.path}</Text>
-      <DiffView patch={args.patch} showLineNumbers />
-    </Box>
-  );
-};
-
-export default defineToolkit({
-  apply_patch: {
-    type: "backend",
-    render: ApplyPatchToolUI,
-  },
-});
-
-```
-
-## tsconfig.json
-
-```json
-{
-  "compilerOptions": {
-    "target": "ESNext",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "jsx": "react-jsx",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "outDir": "dist",
-    "rootDir": "src"
-  },
-  "include": ["src"],
-  "exclude": ["src/dev.ts"]
-}
-
-```
-