@pencil-agent/nano-pencil 2.0.0 → 2.0.1

package/docs/SDK-TESTING.md

@@ -1,364 +0,0 @@
-# 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