@vibesdotdev/runtime-client 0.0.1

package/src/docs/runtime-client.helpers.docs.descriptor.ts

@@ -0,0 +1,354 @@
+import type { DocsTopicDescriptor } from './types.ts';
+
+/**
+ * Descriptor for runtime-client.helpers
+ * getVibesClient() helper functions, surface detection
+ */
+const descriptor: DocsTopicDescriptor = {
+  kind: 'docs/topic',
+  id: 'runtime-client.helpers',
+  title: 'Runtime Client Helpers',
+  summary: 'getVibesClient() helper functions for resolving module clients by id',
+  body: {
+    type: 'markdown',
+    sourceType: 'raw',
+    source: `---
+title: Runtime Client Helpers
+summary: getVibesClient() helper functions for resolving module clients by id
+tags: [runtime-client, helpers, getVibesClient, resolution, singleton]
+parent: runtime-client
+order: 2
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+---
+
+# Runtime Client Helpers
+
+The \`@vibesdotdev/runtime-client\` package exports helper functions for resolving module-level clients without manual \`runtime.query()\` chains. These helpers abstract runtime acquisition, kind registration, and error handling.
+
+## getVibesClient<T>()
+
+Primary helper for resolving a client by id:
+
+\`\`\`ts
+import { getVibesClient } from '@vibesdotdev/runtime-client';
+import type { AIClient } from '@vibesdotdev/ai/client';
+
+const ai = await getVibesClient<AIClient>('ai');
+const response = await ai.generate({ prompt: 'Hello' });
+\`\`\`
+
+### How it works
+
+\`\`\`ts
+// Simplified implementation
+export async function getVibesClient<T extends RuntimeClient>(
+  id: string
+): Promise<T> {
+  const runtime = getVibesRuntime();
+  
+  // Auto-register runtime/client kind if not present
+  if (!runtime.hasKind('runtime/client')) {
+    await runtime.registerPlugin(runtimeClientPlugin);
+  }
+  
+  // Resolve via runtime.query()
+  const client = await runtime
+    .query('runtime/client')
+    .withId(id)
+    .resolve();
+  
+  if (!client) {
+    throw new Error(
+      \`No runtime client registered with id "\${id}". \${
+        'Compose the owning module\\'s plugin (e.g. aiPlugin for id="ai") ' +
+        'before use, and ensure runtimeClientPlugin is registered.'
+      }\`
+    );
+  }
+  
+  return client as T;
+}
+\`\`\`
+
+### Auto-registration semantics
+
+\`getVibesClient()\` automatically registers the \`runtime/client\` kind if it hasn't been registered yet. This means:
+
+1. **No manual bootstrap required** — Call \`getVibesClient()\` directly
+2. **Kind registration is idempotent** — Safe to call multiple times
+3. **Module plugins still needed** — The module owning the client (e.g., \`aiPlugin\`) must still be registered to provide the implementation
+
+\`\`\`ts
+// ✅ Works — runtime/client kind auto-registered
+import { getVibesClient } from '@vibesdotdev/runtime-client';
+import { aiPlugin } from '@vibesdotdev/ai';
+
+const runtime = getVibesRuntime();
+await runtime.registerPlugin(aiPlugin);  // Provides AIClient implementation
+
+const ai = await getVibesClient('ai');  // ✅ Resolves AIClient
+\`\`\`
+
+### Type safety
+
+Use TypeScript generics for type-safe client access:
+
+\`\`\`ts
+import { getVibesClient } from '@vibesdotdev/runtime-client';
+import type { ToolsClient } from '@vibesdotdev/tools/client';
+import type { KnowledgeClient } from '@vibesdotdev/knowledge/client';
+
+// Type-safe resolution
+const tools = await getVibesClient<ToolsClient>('tools');
+const knowledge = await getVibesClient<KnowledgeClient>('knowledge');
+
+// IntelliSense works:
+await tools.listTools();      // ✅ Typed
+await knowledge.search('...'); // ✅ Typed
+\`\`\`
+
+### Error handling
+
+\`getVibesClient()\` throws if the client is not registered:
+
+\`\`\`ts
+try {
+  const ai = await getVibesClient('ai');
+} catch (error) {
+  // Error: No runtime client registered with id "ai".
+  // Compose the owning module's plugin (e.g. aiPlugin for id="ai")
+  // before use, and ensure runtimeClientPlugin is registered.
+}
+\`\`\`
+
+**Common causes:**
+1. Module plugin not registered (e.g., \`aiPlugin\`)
+2. Wrong client id (use \`'ai'\`, not \`'ai-client'\`)
+3. Runtime not bootstrapped (call \`getVibesRuntime()\` first)
+
+## Module-Specific Helper Wrappers
+
+Many packages export their own typed helper that wraps \`getVibesClient()\`:
+
+### Example: Tools
+
+\`\`\`ts
+// packages/tools/src/client/helper.ts
+import { getVibesClient } from '@vibesdotdev/runtime-client';
+import type { ToolsClient } from './runtime-client';
+
+export function getVibesToolsClient(): Promise<ToolsClient> {
+  return getVibesClient<ToolsClient>('tools');
+}
+
+// Usage
+import { getVibesToolsClient } from '@vibesdotdev/tools/client';
+
+const tools = await getVibesToolsClient();
+const toolList = await tools.listTools();
+\`\`\`
+
+### Example: AI
+
+\`\`\`ts
+// packages/ai/src/client/helper.ts
+import { getVibesClient } from '@vibesdotdev/runtime-client';
+import type { AIClient } from './ai-client';
+
+export function getVibesAIClient(): Promise<AIClient> {
+  return getVibesClient<AIClient>('ai');
+}
+
+// Usage
+import { getVibesAIClient } from '@vibesdotdev/ai/client';
+
+const ai = await getVibesAIClient();
+const response = await ai.generate({ prompt: 'Hello' });
+\`\`\`
+
+**Benefits of wrappers:**
+- Type inference without generics
+- Centralized error handling
+- Easier refactoring if client ids change
+- Better IDE autocomplete
+
+## Comparison: getVibesClient() vs runtime.query()
+
+| Aspect | \`getVibesClient()\` | \`runtime.query()\` |
+|--------|---------------------|---------------------|
+| **Verbosity** | Concise | Verbose |
+| **Type safety** | Generic \`<T>\` | Manual casting |
+| **Auto-registration** | Yes | No |
+| **Error messages** | Helpful | Generic |
+| **Use case** | Client resolution | General kind resolution |
+
+\`\`\`ts
+// Verbose: runtime.query()
+const client = await runtime
+  .query('runtime/client')
+  .withId('ai')
+  .resolve() as AIClient;
+
+// Concise: getVibesClient()
+const client = await getVibesClient<AIClient>('ai');
+\`\`\`
+
+**Rule of thumb:** Use \`getVibesClient()\` for client resolution, \`runtime.query()\` for other kinds (tools, providers, models, etc.).
+
+## Surface Detection
+
+The helpers themselves are **surface-neutral** — they work in CLI, SSR, browser, and worker contexts. Surface detection happens at the runtime level:
+
+\`\`\`ts
+// All surfaces use the same helper
+import { getVibesClient } from '@vibesdotdev/runtime-client';
+
+const tools = await getVibesClient('tools');
+
+// Surface is determined by runtime scope:
+// - CLI: { surface: 'cli', hardware: 'consumer' }
+// - SSR: { surface: 'ssr', hardware: 'consumer' }
+// - Browser: { surface: 'browser', hardware: 'consumer' }
+// - Worker: { surface: 'worker', hardware: 'cloud' }
+\`\`\`
+
+The runtime's scope affects **which implementation** is resolved, not **how** it's resolved:
+
+\`\`\`ts
+// In CLI surface
+const runtime = getVibesRuntime();
+runtime.scope; // { surface: 'cli', hardware: 'consumer' }
+
+// In SSR surface (SvelteKit +page.server.ts)
+const runtime = getVibesRuntime();
+runtime.scope; // { surface: 'ssr', hardware: 'consumer' }
+
+// Same helper, different underlying implementations
+const tools = await getVibesClient('tools');
+\`\`\`
+
+See [\`runtime-client.surface\`](runtime-client.surface) for surface-specific initialization patterns.
+
+## WRONG patterns
+
+:::card{title="Anti-patterns"}
+- ❌ **Manual runtime.query() chains** — Use \`getVibesClient()\` for client resolution
+- ❌ **Ignoring type parameters** — Always specify \`getVibesClient<T>()\` for type safety
+- ❌ **Catching and swallowing errors** — Let registration errors surface; they indicate misconfiguration
+- ❌ **Assuming client is cached** — Helper resolves fresh each call; client implementations cache internally
+- ❌ **Using in module scope** — Call at function/call site, not top-level module scope
+:::
+
+## Example: Service layer
+
+\`\`\`ts
+// packages/my-app/src/services/content-generator.ts
+import { getVibesClient } from '@vibesdotdev/runtime-client';
+import type { AIClient } from '@vibesdotdev/ai/client';
+import type { ToolsClient } from '@vibesdotdev/tools/client';
+
+export class ContentGenerator {
+  private aiClient?: AIClient;
+  private toolsClient?: ToolsClient;
+
+  async initialize(): Promise<void> {
+    // Lazy initialization with error handling
+    try {
+      this.aiClient = await getVibesClient<AIClient>('ai');
+      this.toolsClient = await getVibesClient<ToolsClient>('tools');
+    } catch (error) {
+      throw new Error(\`Failed to initialize content generator: \${error}\`);
+    }
+  }
+
+  async generateContent(topic: string): Promise<string> {
+    if (!this.aiClient || !this.toolsClient) {
+      await this.initialize();
+    }
+
+    // Use tools to gather context
+    const context = await this.toolsClient!.runTool('web-search', {
+      query: topic
+    });
+
+    // Generate content with AI
+    const response = await this.aiClient!.generate({
+      prompt: \`Write about \${topic}. Context: \${context}\`,
+      maxTokens: 2000
+    });
+
+    return response;
+  }
+}
+\`\`\`
+
+## Example: Testing
+
+\`\`\`ts
+// packages/my-app/src/__tests__/content-generator.test.ts
+import { describe, it, expect, beforeEach } from 'bun:test';
+import { getVibesRuntime, resetVibesRuntime } from '@vibesdotdev/runtime';
+import { getVibesClient } from '@vibesdotdev/runtime-client';
+import { aiPlugin } from '@vibesdotdev/ai';
+import { toolsPlugin } from '@vibesdotdev/tools';
+
+describe('ContentGenerator', () => {
+  beforeEach(async () => {
+    resetVibesRuntime();
+    const runtime = getVibesRuntime();
+    await runtime.registerPlugin(aiPlugin);
+    await runtime.registerPlugin(toolsPlugin);
+  });
+
+  it('generates content', async () => {
+    const ai = await getVibesClient('ai');
+    const tools = await getVibesClient('tools');
+    
+    // Test with real clients
+    const response = await ai.generate({ prompt: 'Test' });
+    expect(response).toBeDefined();
+  });
+});
+\`\`\`
+
+## Code paths
+
+- Helper implementation: [\`packages/runtime-client/src/helper.ts\`](https://github.com/vibesdotdev/monorepo/tree/main/packages/runtime-client/src/helper.ts)
+- Plugin registration: [\`packages/runtime-client/src/plugin.ts\`](https://github.com/vibesdotdev/monorepo/tree/main/packages/runtime-client/src/plugin.ts)
+- Kind definition: [\`packages/runtime-client/src/kind.ts\`](https://github.com/vibesdotdev/monorepo/tree/main/packages/runtime-client/src/kind.ts)
+
+:::card{title="See also"}
+- [\`runtime-client.api\`](runtime-client.api) — BaseRuntimeClient and extension patterns
+- [\`runtime-client.surface\`](runtime-client.surface) — Surface initialization patterns
+- [\`runtime.query\`](runtime.query) — Runtime query API
+- [\`runtime.plugins\`](runtime.plugins) — Plugin registration and lifecycle
+:::
+`
+  },
+  parent: 'runtime-client',
+  order: 2,
+  tags: ['runtime-client', 'helpers', 'getVibesClient', 'resolution', 'singleton'],
+  surfaces: ['cli', 'web', 'in-app'],
+  hardware: ['consumer', 'cloud'],
+  enabled: true,
+  man: {
+    name: 'runtime-client.helpers — getVibesClient() helper functions',
+    section: 1,
+    synopsis: 'vibes man runtime-client.helpers',
+    options: [],
+    examples: [
+      {
+        description: 'Resolve client by id',
+        command: 'const ai = await getVibesClient<AIClient>("ai")'
+      },
+      {
+        description: 'Use typed wrapper',
+        command: 'const tools = await getVibesToolsClient()'
+      }
+    ],
+    seeAlso: ['runtime-client.api', 'runtime-client.surface', 'runtime.query']
+  }
+};
+
+export default descriptor;