@soulcraft/sdk 1.0.0

package/docs/kit-sdk-guide.md

@@ -0,0 +1,474 @@
+# Kit SDK Integration Guide
+
+This guide is for developers building applications with Soulcraft application kits —
+whether from scratch, extending an existing kit, or integrating with AI assistance.
+It covers how to use `@soulcraft/sdk` to give kit-based applications access to Brainy,
+VFS, AI (Claude), skills, auth, and events.
+
+---
+
+## What Are Kits?
+
+Kits (`@soulcraft/kits`) are pure **configuration** — `kit.json` manifests and
+`SKILL.md` prompt files. They describe a domain, persona, glossary, and workflow.
+They contain no TypeScript logic, no server code, and no SDK imports.
+
+The **application code** that loads and runs a kit is what uses the SDK. That code
+lives in Workshop, Venue, Academy, or your own custom product.
+
+```
+@soulcraft/kits           → Domain config (kit.json, SKILL.md)
+@soulcraft/sdk            → Runtime: Brainy, AI, auth, events, skills
+Your application code     → Wires the two together
+```
+
+---
+
+## Getting Started
+
+Install the SDK in your server application:
+
+```bash
+bun add @soulcraft/sdk @soulcraft/brainy
+```
+
+For server-side use (Node.js, Bun, Hono, SvelteKit server routes):
+
+```typescript
+import { BrainyInstancePool, createSDK, createAuthMiddleware } from '@soulcraft/sdk/server'
+import type { SoulcraftSessionUser } from '@soulcraft/sdk'
+```
+
+For browser/client use (kit app components, SvelteKit frontend):
+
+```typescript
+import { createBrainyProxy, HttpTransport, WsTransport } from '@soulcraft/sdk/client'
+```
+
+---
+
+## Loading a Kit and Accessing Brainy
+
+Every kit application needs a Brainy instance to store and retrieve its graph data.
+Use `BrainyInstancePool` on the server to manage instance lifecycle, then `createSDK`
+to get the full SDK namespace:
+
+```typescript
+import { BrainyInstancePool, createSDK } from '@soulcraft/sdk/server'
+import { kitRegistry } from '@soulcraft/kits'
+
+// One pool per deployment — typically a module singleton
+const pool = new BrainyInstancePool({
+  storage: process.env.STORAGE_TYPE === 'mmap-filesystem' ? 'mmap-filesystem' : 'filesystem',
+  dataPath: process.env.BRAINY_DATA_PATH ?? './brainy-data',
+  strategy: 'per-tenant',   // per-user for Workshop, per-tenant for Venue, per-scope for custom
+  maxInstances: 50,
+  flushOnEvict: true,
+})
+
+// Load the kit config
+const kit = kitRegistry['wicks-and-whiskers']
+console.log(kit.name) // → "Wicks & Whiskers"
+
+// In a request handler: get the Brainy instance for this tenant
+const brain = await pool.forTenant('wicks-charlotte')
+
+// Create the SDK — wraps the brain instance with all namespaces
+const sdk = createSDK({ brain })
+
+// Use Brainy directly through the SDK:
+const candles = await sdk.brainy.find({ query: 'candle inventory' })
+
+// Or use the raw brain instance directly (same thing, different style):
+const candles2 = await brain.find({ query: 'candle inventory' })
+```
+
+---
+
+## Storing Kit Data in Brainy
+
+Kit entities are Brainy graph nodes. Shape your entity types using the noun types
+your kit defines in its `glossary` and `aiExpertise`:
+
+```typescript
+// Add a product entity from a Venue kit
+await sdk.brainy.add({
+  id: 'product-lavender-soy',
+  type: 'Product',
+  metadata: {
+    name: 'Lavender Soy Candle',
+    price: 28.00,
+    category: 'candles',
+    stock: 45,
+    kitId: 'wicks-and-whiskers',
+  }
+})
+
+// Relate it to a category
+await sdk.brainy.relate({
+  from: 'product-lavender-soy',
+  to: 'category-candles',
+  type: 'BelongsTo',
+})
+
+// Find similar products using semantic search
+const similar = await sdk.brainy.find({
+  query: 'soy candle lavender scent',
+  type: 'Product',
+  limit: 10,
+})
+```
+
+---
+
+## Using the VFS for Kit Files
+
+Kits that work with documents, code, or media use the Virtual Filesystem (VFS).
+Access it through `sdk.vfs.*`:
+
+```typescript
+// Write a generated document to the VFS
+await sdk.vfs.writeFile('/projects/my-project/README.md', readmeContent)
+
+// Read it back — returns a Buffer; convert to string for text:
+const buffer = await sdk.vfs.readFile('/projects/my-project/README.md')
+const content = buffer.toString('utf-8')
+
+// List the project directory
+const entries = await sdk.vfs.readdir('/projects/my-project')
+// → ['README.md', 'package.json', 'src']
+
+// File info
+const stat = await sdk.vfs.stat('/projects/my-project/README.md')
+
+// Rename / delete
+await sdk.vfs.rename('/projects/old-name', '/projects/new-name')
+await sdk.vfs.unlink('/projects/my-project/old-file.md')
+```
+
+---
+
+## Loading Skills
+
+Skills (`SKILL.md`) define the AI persona, capabilities, and workflow steps for
+a kit. Load them from the VFS or the bundled `@soulcraft/kits` registry:
+
+```typescript
+// Load a single skill (VFS first, bundled registry fallback):
+const skill = await sdk.skills.load('inventory-health', 'wicks-and-whiskers')
+if (skill) {
+  // Use skill.content (the full SKILL.md string) to build a system prompt
+  console.log(skill.source)  // 'vfs' or 'bundled'
+}
+
+// Load all skills for a kit:
+const skills = await sdk.skills.list({ kitId: 'wicks-and-whiskers' })
+const systemPrompt = buildSystemPrompt(kit, skills.map(s => s.content))
+
+// Install a custom skill into the VFS:
+await sdk.skills.install({
+  id: 'custom-upsell-flow',
+  kitId: 'wicks-and-whiskers',
+  content: `---
+id: custom-upsell-flow
+title: Candle Upsell Flow
+---
+You are an expert at recommending complementary candle products...`,
+})
+```
+
+For the lower-level approach (loading directly from the bundled kits package):
+
+```typescript
+import { skillRegistry } from '@soulcraft/kits'
+
+// skillRegistry['wicks-and-whiskers'] → Record<skillId, content>
+const kitSkills = skillRegistry['wicks-and-whiskers']
+const systemPrompt = buildSystemPrompt(kit, Object.values(kitSkills ?? {}))
+```
+
+---
+
+## AI Integration (Claude)
+
+Use the AI module to interact with Claude in the context of a kit's domain:
+
+```typescript
+import { AI_MODELS } from '@soulcraft/sdk'
+
+// Invoke the AI with the kit's domain context
+const response = await sdk.ai.complete({
+  messages: [{ role: 'user', content: 'What candles are low in stock?' }],
+  systemPrompt: kit.shared.aiPersona,   // kit.json → shared.aiPersona
+  model: AI_MODELS.haiku,              // Haiku for fast queries
+  tools: [
+    {
+      name: 'search_inventory',
+      description: 'Search Brainy for inventory data',
+      inputSchema: {
+        type: 'object',
+        properties: { query: { type: 'string' } },
+        required: ['query'],
+      },
+    }
+  ],
+})
+
+// Handle tool calls — execute the tool and continue the conversation
+if (response.toolCalls) {
+  for (const call of response.toolCalls) {
+    if (call.name === 'search_inventory') {
+      const results = await sdk.brainy.find({
+        query: call.input.query as string,
+        type: 'Product',
+      })
+      // Append a tool_result message and call sdk.ai.complete() again
+    }
+  }
+}
+
+// Streaming — useful for long responses:
+for await (const event of sdk.ai.stream({
+  messages: [{ role: 'user', content: 'Write a product description for lavender candles' }],
+  systemPrompt: kit.shared.aiPersona,
+  model: AI_MODELS.sonnet,
+})) {
+  if (event.type === 'text') process.stdout.write(event.text)
+  if (event.type === 'done') console.log('Tokens used:', event.result.usage)
+}
+```
+
+---
+
+## Events
+
+Subscribe to and emit platform events across the kit application:
+
+```typescript
+// Subscribe to Brainy change events
+sdk.events.on('brainy:change', (event) => {
+  if (event.event === 'add' && event.entity?.nounType === 'Product') {
+    updateInventoryCache(event.entity)
+  }
+})
+
+// Subscribe to VFS events for live document awareness
+sdk.events.on('vfs:write', ({ path, content }) => {
+  if (path.startsWith('/projects/')) {
+    notifyCollaborators(path)
+  }
+})
+
+// Emit custom application events (declare the type first via declaration merging)
+sdk.events.emit('kit:session-completed', {
+  userId: user.id,
+  sessionId,
+  kitId: 'wicks-and-whiskers',
+})
+```
+
+**Note:** The event bus is local to the SDK instance. Events do not cross process
+boundaries. For real-time cross-client events, use the WebSocket transport's `onDataChange`
+or broadcast via your own WebSocket/SSE channel.
+
+---
+
+## Authentication
+
+Kit applications that need user authentication use `createAuthMiddleware` from the
+SDK, wired to a better-auth instance:
+
+```typescript
+import { betterAuth } from 'better-auth'
+import {
+  SOULCRAFT_USER_FIELDS,
+  SOULCRAFT_SESSION_CONFIG,
+  computeEmailHash,
+  createAuthMiddleware,
+} from '@soulcraft/sdk/server'
+
+const auth = betterAuth({
+  database: new Database('./auth.db'),
+  secret: process.env.BETTER_AUTH_SECRET!,
+  session: SOULCRAFT_SESSION_CONFIG,
+  user: { additionalFields: SOULCRAFT_USER_FIELDS },
+  databaseHooks: {
+    user: {
+      create: {
+        before: async (user) => ({
+          data: { ...user, emailHash: computeEmailHash(user.email), platformRole: 'creator' }
+        })
+      }
+    }
+  },
+})
+
+const { requireAuth, optionalAuth } = createAuthMiddleware(auth)
+
+// Protect kit routes
+app.get('/api/kit-data', requireAuth, async (c) => {
+  const user = c.get('user')!   // SoulcraftSessionUser — id, email, emailHash, platformRole
+  const brain = await pool.forUser(user.emailHash, 'my-workspace')
+  const sdk = createSDK({ brain })
+  // ...
+})
+```
+
+**Auth modes:**
+- **Standalone** (dev default, `SOULCRAFT_IDP_URL` not set): better-auth handles auth locally
+- **OIDC** (production, `SOULCRAFT_IDP_URL=https://auth.soulcraft.com`): central IdP handles all auth
+
+---
+
+## Capability Tokens (Cross-Product Access)
+
+When a kit application needs to read from another product's Brainy (e.g. Workshop
+reads from Venue), use capability tokens:
+
+```typescript
+import { createCapabilityToken, verifyCapabilityToken } from '@soulcraft/sdk/server'
+
+// Server A: Issue a scoped token
+const token = await createCapabilityToken({
+  email: user.email,
+  scope: 'wicks-charlotte',
+  ttlMs: 3600 * 1000,
+  secret: process.env.CAPABILITY_TOKEN_SECRET!,
+})
+
+// Server B: Verify it in the RPC handler
+const claims = await verifyCapabilityToken(token, process.env.CAPABILITY_TOKEN_SECRET!)
+if (!claims) return c.json({ error: 'Unauthorized' }, 401)
+```
+
+---
+
+## Full Application Example
+
+A minimal kit application combining auth, Brainy, and AI:
+
+```typescript
+import { Hono } from 'hono'
+import { betterAuth } from 'better-auth'
+import { Database } from 'bun:sqlite'
+import {
+  BrainyInstancePool,
+  createSDK,
+  createAuthMiddleware,
+  SOULCRAFT_USER_FIELDS,
+  SOULCRAFT_SESSION_CONFIG,
+  computeEmailHash,
+} from '@soulcraft/sdk/server'
+import { AI_MODELS } from '@soulcraft/sdk'
+import { kitRegistry } from '@soulcraft/kits'
+
+// ── Kit config ────────────────────────────────────────────────────────────────
+const kit = kitRegistry['wicks-and-whiskers']
+
+// ── Auth ──────────────────────────────────────────────────────────────────────
+const auth = betterAuth({
+  database: new Database('./auth.db'),
+  secret: process.env.BETTER_AUTH_SECRET!,
+  session: SOULCRAFT_SESSION_CONFIG,
+  user: { additionalFields: SOULCRAFT_USER_FIELDS },
+  databaseHooks: {
+    user: {
+      create: {
+        before: async (u) => ({
+          data: { ...u, emailHash: computeEmailHash(u.email), platformRole: 'creator' }
+        })
+      }
+    }
+  },
+})
+const { requireAuth } = createAuthMiddleware(auth)
+
+// ── Brainy pool ───────────────────────────────────────────────────────────────
+const pool = new BrainyInstancePool({
+  storage: 'filesystem',
+  dataPath: './brainy-data',
+  strategy: 'per-user',
+  maxInstances: 100,
+})
+
+// ── Hono app ──────────────────────────────────────────────────────────────────
+const app = new Hono()
+
+app.all('/api/auth/*', (c) => auth.handler(c.req.raw))
+
+app.get('/api/inventory', requireAuth, async (c) => {
+  const user = c.get('user')!
+  const brain = await pool.forUser(user.emailHash, 'main')
+  const sdk = createSDK({ brain })
+
+  const items = await sdk.brainy.find({
+    query: 'inventory items in stock',
+    type: 'Product',
+    limit: 50,
+  })
+
+  return c.json({ kit: kit.name, items })
+})
+
+app.post('/api/ask', requireAuth, async (c) => {
+  const user = c.get('user')!
+  const { question } = await c.req.json<{ question: string }>()
+
+  const brain = await pool.forUser(user.emailHash, 'main')
+  const sdk = createSDK({ brain })
+
+  const skills = await sdk.skills.list({ kitId: 'wicks-and-whiskers' })
+  const systemPrompt = [
+    kit.shared.aiPersona,
+    ...skills.map(s => s.content),
+  ].join('\n\n')
+
+  const response = await sdk.ai.complete({
+    messages: [{ role: 'user', content: question }],
+    systemPrompt,
+    model: AI_MODELS.haiku,
+  })
+
+  return c.json({ answer: response.text })
+})
+
+export default app
+```
+
+---
+
+## Instance Strategies
+
+Choose the pooling strategy that fits your kit application:
+
+| Strategy | When to use | Pool method |
+|----------|-------------|-------------|
+| `per-user` | One Brainy per user (Workshop pattern) | `pool.forUser(emailHash, workspaceId)` |
+| `per-tenant` | One Brainy per organization/location (Venue pattern) | `pool.forTenant(slug)` |
+| `per-scope` | Custom key — Academy's content/learner split, multi-branch, etc. | `pool.forScope(key, factory)` |
+
+Use `per-scope` when:
+- Your kit has multiple instance types (e.g. Academy's content brain vs learner brain)
+- You need multi-branch support (e.g. `userId:workspaceId:branch` key)
+- You need post-init logic in the factory (migrations, integrity checks)
+
+---
+
+## Kit API Reference
+
+| Package | What it provides |
+|---------|-----------------|
+| `@soulcraft/kits` | `kitRegistry`, `skillRegistry`, per-kit TypeScript types |
+| `@soulcraft/sdk` | Shared types, `AI_MODELS`, error classes |
+| `@soulcraft/sdk/server` | `BrainyInstancePool`, `createSDK`, `createAuthMiddleware`, `createBrainyHandler`, `createBrainyWsHandler`, `createBackchannelLogoutHandler`, `computeEmailHash`, `createCapabilityToken`, `verifyCapabilityToken`, `SOULCRAFT_USER_FIELDS`, `SOULCRAFT_SESSION_CONFIG` |
+| `@soulcraft/sdk/client` | `createBrainyProxy`, `HttpTransport`, `WsTransport`, `SseTransport` |
+| `@soulcraft/brainy` | `Brainy` class (peer dep — version must match server) |
+
+---
+
+## See Also
+
+- `docs/USAGE.md` — Full SDK usage reference for all namespaces
+- `docs/ADR-001-sdk-design.md` — Architecture decision record
+- `@soulcraft/kit-schema` — Kit manifest JSON schema and TypeScript types
+- `@soulcraft/kits` — Kit registry with 57+ domain kits

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@soulcraft/sdk",
+  "version": "1.0.0",
+  "description": "The unified Soulcraft platform SDK — data, auth, AI, billing, and notifications",
+  "type": "module",
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "check": "tsc --noEmit",
+    "lint": "eslint src/",
+    "publish:npm": "npm publish --access restricted"
+  },
+  "peerDependencies": {
+    "@soulcraft/brainy": ">=7.17.0",
+    "@soulcraft/cortex": ">=2.1.5",
+    "@soulcraft/hall": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@soulcraft/hall": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
+    "@msgpack/msgpack": "^3.0.0",
+    "better-auth": "^1.0.0",
+    "lru-cache": "^11.0.0"
+  },
+  "devDependencies": {
+    "@soulcraft/hall": "link:@soulcraft/hall",
+    "@types/node": "^22.0.0",
+    "hono": "^4.12.3",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}