@pencil-agent/nano-pencil 2.0.0-beta.9 → 2.0.0

package/docs/SDK-TESTING.md

@@ -0,0 +1,364 @@
+# SDK Testing Guide
+
+## Overview
+
+This document describes the testing strategy and procedures for the NanoPencil SDK.
+
+## Build Verification
+
+### Prerequisites
+
+```bash
+# Ensure Node.js 20+
+node --version
+
+# Install dependencies
+npm install
+```
+
+### Build Test
+
+```bash
+# Full build
+npm run build
+
+# Expected output:
+# - dist/ directory created
+# - TypeScript compiled successfully
+# - All packages bundled
+```
+
+### Pack Verification
+
+```bash
+# Create tarball
+npm pack
+
+# Expected output:
+# - nanopencil-{version}.tgz created
+# - Contains dist/, docs/, README.md
+```
+
+### Install Verification
+
+```bash
+# Create test directory
+mkdir /tmp/sdk-test
+cd /tmp/sdk-test
+
+# Install from tarball
+npm install /path/to/nanopencil-{version}.tgz
+
+# Verify imports
+node -e "
+const sdk = require('@pencil-agent/nano-pencil');
+console.log('Exports:', Object.keys(sdk).slice(0, 10));
+console.log('PencilAgent:', typeof sdk.PencilAgent);
+console.log('createAgentSession:', typeof sdk.createAgentSession);
+"
+```
+
+---
+
+## TypeScript Verification
+
+### Type Imports
+
+```typescript
+import type {
+  PencilAgent,
+  PencilAgentOptions,
+  AgentSession,
+  AgentSessionEvent,
+  CreateAgentSessionOptions,
+  SDKLogger,
+  Tool,
+  ToolDefinition,
+} from '@pencil-agent/nano-pencil'
+
+// All types should be available
+```
+
+### Compilation Test
+
+```bash
+# Create test file
+cat > test-types.ts << 'EOF'
+import { PencilAgent, createAgentSession } from '@pencil-agent/nano-pencil'
+
+const agent = new PencilAgent({ silent: true })
+const session = await createAgentSession({ silent: true })
+EOF
+
+# Compile with tsc
+tsc test-types.ts --noEmit --skipLibCheck
+```
+
+---
+
+## Functional Tests
+
+### Basic Session Creation
+
+```typescript
+import { createAgentSession } from '@pencil-agent/nano-pencil'
+
+async function testBasicSession() {
+  const { session, modelFallbackMessage } = await createAgentSession({
+    cwd: process.cwd(),
+    silent: true,
+    inMemory: true,
+  })
+  
+  console.log('Session created:', !!session)
+  console.log('Model fallback:', modelFallbackMessage)
+  
+  // Send a prompt
+  await session.prompt('Say hello')
+  
+  console.log('Prompt sent successfully')
+}
+
+testBasicSession()
+```
+
+### PencilAgent Wrapper
+
+```typescript
+import { PencilAgent, quickAgent } from '@pencil-agent/nano-pencil'
+
+async function testPencilAgent() {
+  // Test manual init
+  const agent1 = new PencilAgent({ silent: true })
+  await agent1.init()
+  console.log('Manual init:', agent1.isInitialized())
+  
+  // Test quickAgent factory
+  const agent2 = await quickAgent({ silent: true })
+  console.log('quickAgent init:', agent2.isInitialized())
+  
+  // Test run
+  const result = await agent2.run('What is 2+2?')
+  console.log('Run result:', result.length > 0)
+  
+  // Test subscription
+  let eventCount = 0
+  agent2.subscribe((event) => {
+    eventCount++
+  })
+  await agent2.run('Count this')
+  console.log('Events received:', eventCount > 0)
+  
+  // Test shutdown
+  await agent2.shutdown()
+  console.log('Shutdown complete:', !agent2.isInitialized())
+}
+
+testPencilAgent()
+```
+
+### Logger Interface
+
+```typescript
+import { createAgentSession, type SDKLogger } from '@pencil-agent/nano-pencil'
+
+async function testCustomLogger() {
+  const logs: string[] = []
+  
+  const customLogger: SDKLogger = {
+    error: (msg) => logs.push(`ERROR: ${msg}`),
+    warn: (msg) => logs.push(`WARN: ${msg}`),
+    info: (msg) => logs.push(`INFO: ${msg}`),
+  }
+  
+  const { session } = await createAgentSession({
+    silent: false,
+    logger: customLogger,
+    inMemory: true,
+  })
+  
+  console.log('Logger received:', logs.length)
+}
+
+testCustomLogger()
+```
+
+### Silent Mode
+
+```typescript
+import { createAgentSession, silentLogger } from '@pencil-agent/nano-pencil'
+
+async function testSilentMode() {
+  // Option 1: silent flag
+  const { session: s1 } = await createAgentSession({
+    silent: true,
+    inMemory: true,
+  })
+  
+  // Option 2: explicit silent logger
+  const { session: s2 } = await createAgentSession({
+    logger: silentLogger,
+    inMemory: true,
+  })
+  
+  console.log('Both sessions created silently')
+}
+
+testSilentMode()
+```
+
+---
+
+## Event System Test
+
+```typescript
+import { createAgentSession } from '@pencil-agent/nano-pencil'
+
+async function testEventSystem() {
+  const events: string[] = []
+  
+  const { session } = await createAgentSession({
+    silent: true,
+    inMemory: true,
+  })
+  
+  // Subscribe to events
+  session.subscribe((event) => {
+    events.push(event.type)
+  })
+  
+  await session.prompt('Hello')
+  
+  // Expected events:
+  // - message_start
+  // - message_update (multiple)
+  // - message_end
+  // - turn_end
+  
+  console.log('Events captured:', events)
+  console.log('Has message_start:', events.includes('message_start'))
+  console.log('Has turn_end:', events.includes('turn_end'))
+}
+
+testEventSystem()
+```
+
+---
+
+## Error Handling
+
+### SDK Error Event
+
+```typescript
+import { createAgentSession } from '@pencil-agent/nano-pencil'
+
+async function testErrorHandling() {
+  const errors: any[] = []
+  
+  const { session } = await createAgentSession({
+    silent: true,
+    inMemory: true,
+    enableSoul: true, // May trigger sdk:error if soul not available
+  })
+  
+  session.subscribe((event) => {
+    if (event.type === 'sdk:error') {
+      errors.push(event)
+    }
+  })
+  
+  console.log('SDK errors captured:', errors.length)
+}
+
+testErrorHandling()
+```
+
+---
+
+## Integration Test Checklist
+
+| Test | Command | Expected |
+|------|---------|----------|
+| Build | `npm run build` | Success, no errors |
+| Pack | `npm pack` | Tarball created |
+| Types | `tsc test.ts --noEmit` | Success |
+| Session | `createAgentSession()` | Returns session |
+| PencilAgent | `new PencilAgent().init()` | Initializes |
+| quickAgent | `quickAgent()` | Returns initialized agent |
+| Run | `agent.run('hello')` | Returns string |
+| Subscribe | `agent.subscribe(fn)` | Receives events |
+| Logger | `{ logger: customLogger }` | Logs captured |
+| Silent | `{ silent: true }` | No console output |
+| Shutdown | `agent.shutdown()` | Session cleared |
+
+---
+
+## Automated Test Script
+
+```bash
+#!/bin/bash
+# scripts/verify-sdk.sh
+
+set -e
+
+echo "=== SDK Verification ==="
+
+# Build
+echo "1. Building..."
+npm run build
+
+# Pack
+echo "2. Packing..."
+npm pack
+TARBALL=$(ls nanopencil-*.tgz | head -1)
+echo "Tarball: $TARBALL"
+
+# Test install
+echo "3. Testing install..."
+TEST_DIR=/tmp/sdk-test-$(date +%s)
+mkdir -p $TEST_DIR
+cd $TEST_DIR
+npm install $OLDPWD/$TARBALL
+
+# Verify exports
+echo "4. Verifying exports..."
+node -e "
+const sdk = require('@pencil-agent/nano-pencil');
+const exports = ['PencilAgent', 'quickAgent', 'createAgentSession', 'AgentSession', 'silentLogger', 'defaultLogger'];
+for (const e of exports) {
+  if (!sdk[e]) throw new Error('Missing export: ' + e);
+}
+console.log('All exports OK');
+"
+
+# Cleanup
+cd $OLDPWD
+rm -rf $TEST_DIR
+rm -f $TARBALL
+
+echo "=== SDK Verification Complete ==="
+```
+
+---
+
+## Known Limitations
+
+1. **fork()**: Not supported in current version - use separate PencilAgent instances for parallel tasks
+2. **Dynamic tool switching**: Requires session recreation - tools are set at init time
+3. **Streaming API**: Use event subscription instead of async generators - `agent.subscribe()` captures `message_update` events
+4. **Custom tools**: Must be passed via `createAgentSession({ customTools: [...] })` at creation time
+
+---
+
+## Version Compatibility
+
+- Node.js >= 20
+- TypeScript >= 5.3
+- ES Modules (type: "module" in package.json)
+
+---
+
+## See Also
+
+- [SDK.md](./SDK.md) - Full API documentation
+- [API.md](./API.md) - Type definitions reference