@aprovan/stitchery 0.1.0-dev.6bd527d

package/src/prompts.ts

@@ -0,0 +1,326 @@
+export const PATCHWORK_PROMPT = `
+You are a friendly assistant! When responding to the user, you _must_ respond with JSX files!
+
+Look at 'patchwork.compilers' to see what specific runtime components and libraries are supported. (e.g. '['@aprovan/patchwork-image-shadcn' supports React, Tailwind, & ShadCN components). If there are no compilers, respond as you normally would. If compilers are available, ALWAYS respond with a component following [Component Generation](#component-generation).
+
+Look at 'patchwork.services' to see what services are available for widgets to call. If services are listed, you can generate widgets that make service calls using global namespace objects.
+
+**IMPORTANT: If you need to discover available services or get details about a specific service, use the \`search_services\` tool.**
+
+## Component Generation
+
+Respond with code blocks using tagged attributes on the fence line. The \`note\` attribute (optional but encouraged) provides a brief description visible in the UI. The \`path\` attribute specifies the virtual file path.
+
+### Code Block Format
+
+\`\`\`tsx note="Main component" path="components/weather/main.tsx"
+export default function WeatherWidget() {
+  // component code
+}
+\`\`\`
+
+### Attribute Order
+Put \`note\` first so it's available soonest in streaming UI.
+
+### Multi-File Generation
+
+When generating complex widgets, you can output multiple files. Use the \`@/\` prefix for virtual file system paths. ALWAYS prefer to generate visible components before metadata.
+
+**Example multi-file widget:**
+
+\`\`\`json note="Widget configuration" path="components/dashboard/package.json"
+{
+  "description": "Interactive dashboard widget",
+  "patchwork": {
+    "inputs": {
+      "type": "object",
+      "properties": {
+        "title": { "type": "string" }
+      }
+    },
+    "services": {
+      "analytics": ["getMetrics", "getChartData"]
+    }
+  }
+}
+\`\`\`
+
+\`\`\`tsx note="Main widget component" path="components/dashboard/main.tsx"
+import { Card } from './Card';
+import { Chart } from './Chart';
+
+export default function Dashboard({ title = "Dashboard" }) {
+  return (
+    <div>
+      <h1>{title}</h1>
+      <Card />
+      <Chart />
+    </div>
+  );
+}
+\`\`\`
+
+\`\`\`tsx note="Card subcomponent" path="components/dashboard/Card.tsx"
+export function Card() {
+  return <div className="p-4 rounded border">Card content</div>;
+}
+\`\`\`
+
+### Requirements
+- DO think heavily about correctness of code and syntax
+- DO keep things simple and self-contained
+- ALWAYS include the \`path\` attribute specifying the file location. Be generic with the name and describe the general component's use
+- ALWAYS output the COMPLETE code block with opening \`\`\`tsx and closing \`\`\` markers
+- Use \`note\` attribute to describe what each code block does (optional but encouraged)
+- NEVER truncate or cut off code - finish the entire component before stopping
+- If the component is complex, simplify it rather than leaving it incomplete
+- Do NOT include: a heading/title
+
+### Visual Design Guidelines
+Create professional, polished interfaces that present information **spatially** rather than as vertical lists:
+- Use **cards, grids, and flexbox layouts** to organize related data into visual groups
+- Leverage **icons** (from lucide-react) alongside text to communicate meaning at a glance
+- Apply **visual hierarchy** through typography scale, weight, and color contrast
+- Use **whitespace strategically** to create breathing room and separation
+- Prefer **horizontal arrangements** where data fits naturally (e.g., stats in a row, badges inline)
+- Group related metrics into **compact visual clusters** rather than separate line items
+- Use **subtle backgrounds, borders, and shadows** to define sections without heavy dividers
+
+### Root Element Constraints
+The component will be rendered inside a parent container that handles positioning. Your root element should:
+- ✅ Use intrinsic sizing (let content determine dimensions)
+- ✅ Handle internal padding (e.g., \`p-4\`, \`p-6\`)
+- ❌ NEVER add centering utilities (\`items-center\`, \`justify-center\`) to position itself
+- ❌ NEVER add viewport-relative sizing (\`min-h-screen\`, \`h-screen\`, \`w-screen\`)
+- ❌ NEVER add flex/grid on root just for self-centering
+
+### Using Services in Widgets (CRITICAL)
+
+**MANDATORY workflow - you must follow these steps IN ORDER:**
+
+1. **Use \`search_services\`** to discover the service schema
+2. **STOP. Make an actual call to the service tool itself** (e.g., \`weather_get_forecast\`, \`github_get_repo\`) with real arguments. This is NOT optional. Do NOT skip this step.
+3. **Observe the response** - verify it succeeded and note the exact data structure
+4. **Only then generate the widget** that fetches the same data at runtime
+
+**\`search_services\` is NOT a substitute for calling the actual service.** It only returns documentation. You MUST invoke the real service tool to validate your arguments work.
+
+**Tool naming:** Service tools use underscores, not dots. For example: \`weather_get_forecast\`, \`github_list_repos\`.
+
+**Example workflow for a weather widget:**
+\`\`\`
+Step 1: search_services({ query: "weather" })
+        → Learn that weather_get_current_conditions exists with params: { latitude, longitude }
+
+Step 2: weather_get_current_conditions({ latitude: 29.7604, longitude: -95.3698 })  ← REQUIRED!
+        → Verify it returns { temp: 72, humidity: 65, ... }
+
+Step 3: Generate widget that calls weather.get_current_conditions at runtime
+\`\`\`
+
+**If you skip Step 2, you will generate broken widgets.** Arguments that look correct in the schema may fail at runtime due to validation rules, required formats, or service-specific constraints.
+
+**NEVER embed static data directly in the component.**
+
+❌ **WRONG** - Embedding data directly:
+\`\`\`tsx path="components/weather/bad-example.tsx"
+// DON'T DO THIS - calling tool, then embedding the response as static data
+export default function WeatherWidget() {
+  // Static data embedded at generation time - BAD!
+  const weather = { temp: 72, condition: "sunny", humidity: 45 };
+  return <div>Temperature: {weather.temp}°F</div>;
+}
+\`\`\`
+
+✅ **CORRECT** - Fetching data at runtime:
+\`\`\`tsx note="Weather widget with runtime data" path="components/weather/main.tsx"
+export default function WeatherWidget() {
+  const [data, setData] = useState(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+
+  useEffect(() => {
+    // Fetch data at runtime - GOOD!
+    weather.get_forecast({ latitude: 48.8566, longitude: 2.3522 })
+      .then(setData)
+      .catch(setError)
+      .finally(() => setLoading(false));
+  }, []);
+
+  if (loading) return <Skeleton className="h-32 w-full" />;
+  if (error) return <Alert variant="destructive">{error.message}</Alert>;
+  
+  return <div>Temperature: {data.temp}°F</div>;
+}
+\`\`\`
+
+**Why this matters:**
+- Widgets with runtime service calls show **live data** that updates when refreshed
+- Static embedded data becomes **stale immediately** after generation
+- The proxy pattern allows widgets to be **reusable** across different contexts
+- Error handling and loading states improve **user experience**
+
+**Service call pattern:**
+\`\`\`tsx
+// Services are available as global namespace objects
+// Call format: namespace.procedure_name({ ...args })
+
+const [data, setData] = useState(null);
+const [loading, setLoading] = useState(true);
+const [error, setError] = useState(null);
+
+useEffect(() => {
+  serviceName.procedure_name({ param1: value1 })
+    .then(setData)
+    .catch(setError)
+    .finally(() => setLoading(false));
+}, [/* dependencies */]);
+\`\`\`
+
+**Required for service-using widgets:**
+- Always show loading indicators (Skeleton, Loader2 spinner, etc.)
+- Always handle errors gracefully with user-friendly messages
+- Use appropriate React hooks (useState, useEffect) for async data
+- Services are injected as globals - NO imports needed
+
+### Validating Service Calls (CRITICAL - READ CAREFULLY)
+
+**Calling \`search_services\` multiple times is NOT validation.** You must call the actual service tool.
+
+❌ **WRONG workflow (will produce broken widgets):**
+\`\`\`
+1. search_services({ query: "weather" })     ← Only gets schema
+2. search_services({ query: "location" })    ← Still only schema
+3. Generate widget                           ← BROKEN - never tested the actual service!
+\`\`\`
+
+✅ **CORRECT workflow:**
+\`\`\`
+1. search_services({ query: "weather" })           ← Get schema
+2. weather_get_forecast({ latitude: 29.76, longitude: -95.37 })  ← ACTUALLY CALL IT
+3. Observe response: { temp: 72, conditions: "sunny", ... }
+4. Generate widget that calls weather.get_forecast at runtime
+\`\`\`
+
+**The service tool (e.g., \`weather_get_forecast\`, \`github_list_repos\`) is a DIFFERENT tool from \`search_services\`.** You have access to both. Use both.
+
+**Only after a successful test call to the actual service should you generate the widget.**
+
+### Component Parameterization (IMPORTANT)
+
+**Widgets should accept props for dynamic values instead of hardcoding:**
+
+❌ **WRONG** - Hardcoded values:
+\`\`\`tsx path="components/weather/bad-example.tsx"
+export default function WeatherWidget() {
+  // Location hardcoded - BAD!
+  const [lat, lon] = [48.8566, 2.3522]; // Paris
+  // ...
+}
+\`\`\`
+
+✅ **CORRECT** - Parameterized with props and defaults:
+\`\`\`tsx note="Parameterized weather widget" path="components/weather/main.tsx"
+interface WeatherWidgetProps {
+  location?: string;    // e.g., "Paris, France"
+  latitude?: number;    // Direct coordinates (optional)
+  longitude?: number;
+}
+
+export default function WeatherWidget({ 
+  location = "Paris, France",
+  latitude,
+  longitude 
+}: WeatherWidgetProps) {
+  // Use provided coordinates or look up from location name
+  // ...
+}
+\`\`\`
+
+**Why parameterize:**
+- Components become **reusable** across different contexts
+- Users can **customize behavior** without editing code
+- Enables **composition** - parent components can pass different values
+- Supports **testing** with various inputs
+
+**What to parameterize:**
+- Location names, coordinates, IDs
+- Search queries and filters
+- Display options (count, format, theme)
+- API-specific identifiers (usernames, repo names, etc.)
+
+### Anti-patterns to Avoid
+- ❌ Bulleted or numbered lists of key-value pairs
+- ❌ Vertical stacks where horizontal layouts would fit
+- ❌ Plain text labels without visual treatment
+- ❌ Uniform styling that doesn't distinguish primary from secondary information
+- ❌ Wrapping components in centering containers (parent handles this)
+- ❌ **Embedding API response data directly in components instead of fetching at runtime**
+- ❌ **Calling a tool, then putting the response as static JSX/JSON in the generated code**
+- ❌ **Hardcoding values that should be component props**
+- ❌ **Calling \`search_services\` multiple times instead of calling the actual service tool**
+- ❌ **Generating a widget without first making a real call to the service with your intended arguments**
+- ❌ **Treating schema documentation as proof that a service call will work**
+- ❌ **Omitting the \`path\` attribute on code blocks**
+`;
+
+export const EDIT_PROMPT = `
+You are editing an existing JSX component. The user will provide the current code and describe the changes they want.
+
+## Response Format
+
+Use code fences with tagged attributes. The \`note\` attribute (optional but encouraged) provides a brief description visible in the UI. The \`path\` attribute specifies the target file.
+
+\`\`\`diff note="Brief description of this change" path="@/components/Button.tsx"
+<<<<<<< SEARCH
+exact code to find
+=======
+replacement code
+>>>>>>> REPLACE
+\`\`\`
+
+### Attribute Order
+Put \`note\` first so it's available soonest in streaming UI.
+
+### Multi-File Edits
+When editing multiple files, use the \`path\` attribute with virtual paths (\`@/\` prefix for generated files):
+
+\`\`\`diff note="Update button handler" path="@/components/Button.tsx"
+<<<<<<< SEARCH
+onClick={() => {}}
+=======
+onClick={() => handleClick()}
+>>>>>>> REPLACE
+\`\`\`
+
+\`\`\`diff note="Add utility function" path="@/lib/utils.ts"
+<<<<<<< SEARCH
+export const formatDate = ...
+=======
+export const formatDate = ...
+
+export const handleClick = () => console.log('clicked');
+>>>>>>> REPLACE
+\`\`\`
+
+## Rules
+- SEARCH block must match the existing code EXACTLY (whitespace, indentation, everything)
+- You can include multiple diff blocks for multiple changes
+- Each diff block should have its own \`note\` attribute annotation
+- Keep changes minimal and targeted
+- Do NOT output the full file - only the diffs
+- If clarification is needed, ask briefly before any diffs
+
+## CRITICAL: Diff Marker Safety
+- NEVER include the strings "<<<<<<< SEARCH", "=======", or ">>>>>>> REPLACE" inside your replacement code
+- These are reserved markers for parsing the diff format
+- If you need to show diff-like content, use alternative notation (e.g., "// old code" / "// new code")
+- Malformed diff markers will cause the edit to fail
+
+## Summary
+After all diffs, provide a brief markdown summary of the changes made. Use formatting like:
+- **Bold** for emphasis on key changes
+- Bullet points for listing multiple changes
+- Keep it concise (2-4 lines max)
+- Do NOT include: a heading/title
+`;

package/src/server/index.ts

@@ -0,0 +1,365 @@
+import { createServer, type Server } from "node:http";
+import { createMCPClient } from "@ai-sdk/mcp";
+import { Experimental_StdioMCPTransport } from "@ai-sdk/mcp/mcp-stdio";
+import { createUtcpBackend } from "@aprovan/patchwork-utcp";
+import { jsonSchema, type Tool } from "ai";
+import type { ServerConfig, McpServerConfig } from "../types.js";
+import { handleChat, handleEdit, type RouteContext } from "./routes.js";
+import { handleLocalPackages } from "./local-packages.js";
+import { handleVFS, type VFSContext } from "./vfs-routes.js";
+import { ServiceRegistry, generateServicesPrompt } from "./services.js";
+
+export interface StitcheryServer {
+  server: Server;
+  registry: ServiceRegistry;
+  start(): Promise<{ port: number; host: string }>;
+  stop(): Promise<void>;
+}
+
+async function initMcpTools(
+  configs: McpServerConfig[],
+  registry: ServiceRegistry,
+): Promise<void> {
+  for (const config of configs) {
+    const client = await createMCPClient({
+      transport: new Experimental_StdioMCPTransport({
+        command: config.command,
+        args: config.args,
+      }),
+    });
+    // Use MCP server name as namespace for all tools from this server
+    registry.registerTools(await client.tools(), config.name);
+  }
+}
+
+const searchServicesSchema = {
+  type: "object",
+  properties: {
+    query: {
+      type: "string",
+      description:
+        'Natural language description of what you want to do (e.g., "get weather forecast", "list github repos")',
+    },
+    namespace: {
+      type: "string",
+      description:
+        'Filter results to a specific service namespace (e.g., "weather", "github")',
+    },
+    tool_name: {
+      type: "string",
+      description: "Get detailed info about a specific tool by name",
+    },
+    limit: {
+      type: "number",
+      description: "Maximum number of results to return",
+      default: 10,
+    },
+    include_interfaces: {
+      type: "boolean",
+      description: "Include TypeScript interface definitions in results",
+      default: true,
+    },
+  },
+} as const;
+
+interface SearchServicesArgs {
+  query?: string;
+  namespace?: string;
+  tool_name?: string;
+  limit?: number;
+  include_interfaces?: boolean;
+}
+
+/**
+ * Create the search_services tool for LLM use
+ */
+function createSearchServicesTool(registry: ServiceRegistry): Tool {
+  return {
+    description: `Search for available services/tools. Use this to discover what APIs are available for widgets to call.
+
+Returns matching services with their TypeScript interfaces. Use when:
+- You need to find a service to accomplish a task
+- You want to explore available APIs in a namespace
+- You need the exact interface/parameters for a service call`,
+    inputSchema: jsonSchema<SearchServicesArgs>(searchServicesSchema),
+    execute: async (args: SearchServicesArgs) => {
+      // If requesting specific tool info
+      if (args.tool_name) {
+        const info = registry.getToolInfo(args.tool_name);
+        if (!info) {
+          return {
+            success: false,
+            error: `Tool '${args.tool_name}' not found`,
+          };
+        }
+        return { success: true, tool: info };
+      }
+
+      // Search for tools
+      const results = registry.searchServices({
+        query: args.query,
+        namespace: args.namespace,
+        limit: args.limit ?? 10,
+        includeInterfaces: args.include_interfaces ?? true,
+      });
+
+      return {
+        success: true,
+        count: results.length,
+        tools: results,
+        namespaces: registry.getNamespaces(),
+      };
+    },
+  };
+}
+
+function parseBody<T>(req: import("node:http").IncomingMessage): Promise<T> {
+  return new Promise((resolve, reject) => {
+    let body = "";
+    req.on("data", (chunk) => (body += chunk));
+    req.on("end", () => {
+      try {
+        resolve(JSON.parse(body));
+      } catch (err) {
+        reject(err);
+      }
+    });
+    req.on("error", reject);
+  });
+}
+
+export async function createStitcheryServer(
+  config: Partial<ServerConfig> = {},
+): Promise<StitcheryServer> {
+  const {
+    port = 6434,
+    host = "127.0.0.1",
+    copilotProxyUrl = "http://127.0.0.1:6433/v1",
+    localPackages = {},
+    mcpServers = [],
+    utcp,
+    vfsDir,
+    vfsUsePaths = false,
+    verbose = false,
+  } = config;
+
+  const log = verbose
+    ? (...args: unknown[]) => console.log("[stitchery]", ...args)
+    : () => {};
+
+  // Create service registry
+  const registry = new ServiceRegistry();
+
+  log("Initializing MCP tools...");
+  await initMcpTools(mcpServers, registry);
+  log(`Loaded ${registry.size} tools from ${mcpServers.length} MCP servers`);
+
+  // Initialize UTCP backend if config provided
+  if (utcp) {
+    log("Initializing UTCP backend...");
+    log("UTCP config:", JSON.stringify(utcp, null, 2));
+    try {
+      // Cast to unknown since createUtcpBackend uses UtcpClientConfigSerializer to validate
+      const { backend, toolInfos } = await createUtcpBackend(
+        utcp as unknown as Parameters<typeof createUtcpBackend>[0],
+        utcp.cwd,
+      );
+      registry.registerBackend(backend, toolInfos);
+      log(
+        `Registered UTCP backend with ${toolInfos.length} tools:`,
+        toolInfos.map((tool: { name: string }) => tool.name).join(", "),
+      );
+    } catch (err) {
+      console.error("[stitchery] Failed to initialize UTCP backend:", err);
+    }
+  }
+
+  log("Local packages:", localPackages);
+
+  // Create internal tools (search_services, etc.)
+  const internalTools = {
+    search_services: createSearchServicesTool(registry),
+  };
+
+  // Combine MCP tools with internal tools
+  const allTools = { ...registry.getTools(), ...internalTools };
+
+  const routeCtx: RouteContext = {
+    copilotProxyUrl,
+    tools: allTools,
+    registry,
+    servicesPrompt: generateServicesPrompt(registry),
+    log,
+  };
+
+  const localPkgCtx = { localPackages, log };
+
+  const vfsCtx: VFSContext | null = vfsDir
+    ? { rootDir: vfsDir, usePaths: vfsUsePaths, log }
+    : null;
+
+  const server = createServer(async (req, res) => {
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader(
+      "Access-Control-Allow-Methods",
+      "GET, POST, PUT, DELETE, HEAD, OPTIONS",
+    );
+    res.setHeader(
+      "Access-Control-Allow-Headers",
+      "Content-Type, Authorization",
+    );
+
+    if (req.method === "OPTIONS") {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    const url = req.url || "/";
+    log(`${req.method} ${url}`);
+
+    try {
+      if (handleLocalPackages(req, res, localPkgCtx)) {
+        return;
+      }
+
+      if (vfsCtx && handleVFS(req, res, vfsCtx)) {
+        return;
+      }
+
+      if (url === "/api/chat" && req.method === "POST") {
+        await handleChat(req, res, routeCtx);
+        return;
+      }
+
+      if (url === "/api/edit" && req.method === "POST") {
+        await handleEdit(req, res, routeCtx);
+        return;
+      }
+
+      // Service proxy endpoint for widgets
+      const proxyMatch = url.match(/^\/api\/proxy\/([^/]+)\/(.+)$/);
+      if (proxyMatch && req.method === "POST") {
+        const [, namespace, procedure] = proxyMatch;
+        try {
+          const body = await parseBody<{ args?: unknown }>(req);
+          const result = await registry.call(
+            namespace!,
+            procedure!,
+            body.args ?? {},
+          );
+          res.setHeader("Content-Type", "application/json");
+          res.writeHead(200);
+          res.end(JSON.stringify(result));
+        } catch (err) {
+          log("Proxy error:", err);
+          res.setHeader("Content-Type", "application/json");
+          res.writeHead(500);
+          res.end(
+            JSON.stringify({
+              error: err instanceof Error ? err.message : "Service call failed",
+            }),
+          );
+        }
+        return;
+      }
+
+      // Services search endpoint (POST with body for complex queries)
+      if (url === "/api/services/search" && req.method === "POST") {
+        const body = await parseBody<{
+          query?: string;
+          namespace?: string;
+          tool_name?: string;
+          limit?: number;
+          include_interfaces?: boolean;
+        }>(req);
+
+        res.setHeader("Content-Type", "application/json");
+        res.writeHead(200);
+
+        if (body.tool_name) {
+          const info = registry.getToolInfo(body.tool_name);
+          if (!info) {
+            res.end(
+              JSON.stringify({
+                success: false,
+                error: `Tool '${body.tool_name}' not found`,
+              }),
+            );
+          } else {
+            res.end(JSON.stringify({ success: true, tool: info }));
+          }
+          return;
+        }
+
+        const results = registry.searchServices({
+          query: body.query,
+          namespace: body.namespace,
+          limit: body.limit ?? 20,
+          includeInterfaces: body.include_interfaces ?? false,
+        });
+
+        res.end(
+          JSON.stringify({
+            success: true,
+            count: results.length,
+            tools: results,
+            namespaces: registry.getNamespaces(),
+          }),
+        );
+        return;
+      }
+
+      // Services metadata endpoint
+      if (url === "/api/services" && req.method === "GET") {
+        res.setHeader("Content-Type", "application/json");
+        res.writeHead(200);
+        res.end(
+          JSON.stringify({
+            namespaces: registry.getNamespaces(),
+            services: registry.getServiceInfo(),
+          }),
+        );
+        return;
+      }
+
+      if (url === "/health" || url === "/") {
+        res.setHeader("Content-Type", "application/json");
+        res.writeHead(200);
+        res.end(JSON.stringify({ status: "ok", service: "stitchery" }));
+        return;
+      }
+
+      res.writeHead(404);
+      res.end(`Not found: ${url}`);
+    } catch (err) {
+      log("Error:", err);
+      res.writeHead(500);
+      res.end(err instanceof Error ? err.message : "Internal server error");
+    }
+  });
+
+  return {
+    server,
+    registry,
+
+    async start() {
+      return new Promise((resolve, reject) => {
+        server.on("error", reject);
+        server.listen(port, host, () => {
+          log(`Server listening on http://${host}:${port}`);
+          resolve({ port, host });
+        });
+      });
+    },
+
+    async stop() {
+      return new Promise((resolve, reject) => {
+        server.close((err) => {
+          if (err) reject(err);
+          else resolve();
+        });
+      });
+    },
+  };
+}