@positronic/template-new-project 0.0.2

package/template/docs/brain-testing-guide.md

@@ -0,0 +1,307 @@
+# Brain Testing Guide
+
+This guide explains how to test Positronic brains using the testing utilities provided by `@positronic/core`.
+
+## Testing Philosophy
+
+Following the principles from [Kent C. Dodds' testing philosophy](https://kentcdodds.com/blog/write-tests):
+- **Write tests. Not too many. Mostly integration.**
+- Test user outcomes, not implementation details
+- Focus on what your brain produces, not how it produces it
+
+## Overview
+
+Testing brains is about verifying they produce the correct outputs given specific AI responses. The testing utilities make it easy to mock AI responses and assert on the final results.
+
+## Quick Start
+
+```typescript
+import { createMockClient, runBrainTest } from '@positronic/core';
+import yourBrain from './your-brain.js';
+
+describe('your-brain', () => {
+  it('should process user data and generate a report', async () => {
+    // Arrange: Set up AI responses
+    const mockClient = createMockClient();
+    mockClient.mockResponses(
+      { analysis: 'User shows high engagement', score: 0.85 },
+      { report: 'Detailed engagement report...', recommendations: ['A', 'B'] }
+    );
+
+    // Act: Run the brain
+    const result = await runBrainTest(yourBrain, { client: mockClient });
+
+    // Assert: Verify the outcome
+    expect(result.completed).toBe(true);
+    expect(result.finalState.report).toContain('Detailed engagement report');
+    expect(result.finalState.recommendations).toHaveLength(2);
+  });
+});
+```
+
+## API Reference
+
+### runBrainTest
+
+```typescript
+const result = await runBrainTest(brain, {
+  client: mockClient,           // Optional: defaults to createMockClient()
+  initialState: { count: 0 },   // Optional: initial state
+  resources: resourceLoader,    // Optional: resources
+  brainOptions: { mode: 'test' } // Optional: brain-specific options
+});
+```
+
+**Returns:**
+- `completed: boolean` - Whether the brain completed successfully
+- `error: Error | null` - Any error that occurred
+- `finalState: State` - The final state after all steps
+- `steps: string[]` - Names of executed steps in order
+
+## MockObjectGenerator API
+
+### Creating a Mock Client
+
+```typescript
+const mockClient = createMockClient();
+```
+
+### Mocking Responses
+
+#### Single Response
+```typescript
+mockClient.mockNextResponse({
+  answer: 'The capital of France is Paris',
+  confidence: 0.95
+});
+```
+
+#### Multiple Responses
+```typescript
+mockClient.mockResponses(
+  { step1: 'completed' },
+  { step2: 'processed' },
+  { finalResult: 'success' }
+);
+```
+
+#### Error Responses
+```typescript
+mockClient.mockNextError('API rate limit exceeded');
+// or
+mockClient.mockNextError(new Error('Connection timeout'));
+```
+
+### Assertions
+
+```typescript
+// Check call count
+mockClient.expectCallCount(3);
+
+// Check call parameters
+mockClient.expectCalledWith({
+  prompt: 'Generate a summary',
+  schemaName: 'summarySchema'
+});
+
+// Get call history
+const calls = mockClient.getCalls();
+```
+
+## Testing Patterns
+
+### Testing Success Cases
+
+Focus on what the brain produces for the user:
+
+```typescript
+it('should generate personalized recommendations', async () => {
+  // Arrange
+  mockClient.mockResponses(
+    { preferences: ['tech', 'sports'], confidence: 0.9 },
+    { recommendations: ['Item A', 'Item B', 'Item C'] }
+  );
+
+  // Act
+  const result = await runBrainTest(recommendationBrain, {
+    client: mockClient,
+    initialState: { userId: '123' }
+  });
+
+  // Assert outcomes, not implementation
+  expect(result.completed).toBe(true);
+  expect(result.finalState.recommendations).toHaveLength(3);
+  expect(result.finalState.confidence).toBeGreaterThan(0.8);
+});
+```
+
+### Testing Error Cases
+
+```typescript
+it('should handle API failures gracefully', async () => {
+  // Arrange
+  mockClient.mockNextError('Service temporarily unavailable');
+
+  // Act
+  const result = await runBrainTest(processingBrain, { client: mockClient });
+
+  // Assert
+  expect(result.completed).toBe(false);
+  expect(result.error?.message).toBe('Service temporarily unavailable');
+});
+```
+
+### Testing State Flow
+
+Verify that data flows correctly through your brain:
+
+```typescript
+it('should use customer data to generate personalized content', async () => {
+  // Arrange
+  const customerName = 'Alice';
+  mockClient.mockResponses(
+    { greeting: 'Hello Alice!', tone: 'friendly' },
+    { email: 'Personalized email content...' }
+  );
+
+  // Act
+  const result = await runBrainTest(emailBrain, {
+    client: mockClient,
+    initialState: { customerName }
+  });
+
+  // Assert that the AI used the customer data
+  const calls = mockClient.getCalls();
+  expect(calls[0].params.prompt).toContain(customerName);
+  expect(result.finalState.email).toContain('Personalized email content');
+});
+```
+
+## Best Practices
+
+1. **Test Behavior, Not Implementation**
+   - ✅ Test what the brain produces
+   - ❌ Don't test internal event sequences
+   - ❌ Don't test step counts unless it's a user requirement
+
+2. **Use Descriptive Test Names**
+   - ✅ `it('should generate a summary from user feedback')`
+   - ❌ `it('should complete 4 steps and emit events')`
+
+3. **Keep Tests Simple**
+   - Arrange: Set up mock responses
+   - Act: Run the brain
+   - Assert: Check the outcome
+
+4. **Test Edge Cases That Matter**
+   - API errors
+   - Empty responses
+   - Invalid data that could affect users
+
+## What Not to Test
+
+Following testing best practices, avoid testing:
+
+1. **Implementation Details**
+   - Don't check specific event types
+   - Don't verify internal state transformations
+   - Don't count patch operations
+
+2. **Framework Behavior**
+   - Trust that the brain framework works
+   - Don't test that steps execute in order
+   - Don't verify event emission
+
+3. **Mock Behavior**
+   - Don't test that mocks were called (unless verifying data flow)
+   - Focus on what the brain does with the responses
+
+## Complete Example
+
+```typescript
+import { createMockClient, runBrainTest } from '@positronic/core';
+import analysisBrain from './analysis-brain.js';
+
+describe('analysis-brain', () => {
+  let mockClient;
+
+  beforeEach(() => {
+    mockClient = createMockClient();
+  });
+
+  it('should analyze customer feedback and generate insights', async () => {
+    // Arrange: Set up AI to return analysis
+    mockClient.mockNextResponse({
+      sentiment: 'positive',
+      keywords: ['innovation', 'quality', 'service'],
+      summary: 'Customers appreciate product quality and innovation'
+    });
+
+    // Act: Run analysis on customer feedback
+    const result = await runBrainTest(analysisBrain, { 
+      client: mockClient,
+      initialState: { 
+        feedback: 'Your product is innovative and high quality...'
+      }
+    });
+
+    // Assert: Verify we got actionable insights
+    expect(result.completed).toBe(true);
+    expect(result.finalState.insights).toEqual({
+      sentiment: 'positive',
+      topThemes: ['innovation', 'quality', 'service'],
+      actionable: true,
+      summary: 'Customers appreciate product quality and innovation'
+    });
+  });
+
+  it('should handle analysis service outages', async () => {
+    // Arrange: Simulate service failure
+    mockClient.mockNextError('Analysis service unavailable');
+
+    // Act: Attempt analysis
+    const result = await runBrainTest(analysisBrain, { 
+      client: mockClient,
+      initialState: { feedback: 'Some feedback...' }
+    });
+    
+    // Assert: Verify graceful failure
+    expect(result.completed).toBe(false);
+    expect(result.error?.message).toBe('Analysis service unavailable');
+  });
+});
+```
+
+## Troubleshooting
+
+### TypeScript Issues
+
+The test utilities are fully typed. If you get type errors:
+```typescript
+// ✅ Type-safe: result.finalState is typed as your brain's state
+const result = await runBrainTest(myBrain, { initialState });
+expect(result.finalState.myProperty).toBe('value');
+```
+
+### Common Issues
+
+1. **Mock count mismatch**: Ensure you mock the same number of responses as AI calls in your brain
+2. **State assertions failing**: Check that your brain is actually setting the expected state
+3. **Completion is false**: Your brain might be throwing an error - check `result.error`
+
+### Debugging Tips
+
+```typescript
+// See what prompts are being sent to AI
+const calls = mockClient.getCalls();
+console.log('AI prompts:', calls.map(c => c.params.prompt));
+
+// Check execution order
+console.log('Steps executed:', result.steps);
+```
+
+## Next Steps
+
+- Review the [Brain DSL Guide](./brain-dsl-guide.md) for more information on brain structure
+- Check example tests in the codebase for real-world testing patterns
+- Remember: focus on testing what matters to users, not how the brain works internally

package/template/docs/positronic-guide.md

@@ -0,0 +1,236 @@
+# Positronic Project Guide
+
+This guide covers project-level patterns and best practices for Positronic applications.
+
+## Project Structure
+
+A typical Positronic project has the following structure:
+
+```
+├── brain.ts         # Project brain wrapper
+├── brains/          # Brain definitions
+├── resources/       # Files accessible to brains
+├── tests/           # Test files
+├── docs/            # Documentation
+├── runner.ts        # Local runner for development
+└── positronic.config.json  # Project configuration
+```
+
+## The Project Brain Pattern
+
+Every Positronic project includes a `brain.ts` file in the root directory. This file exports a custom `brain` function that wraps the core Positronic brain function.
+
+### Why Use a Project Brain?
+
+The project brain pattern provides a single place to:
+- Configure services that all brains can access
+- Set up logging, monitoring, or analytics
+- Add authentication or API clients
+- Establish project-wide conventions
+
+### Basic Usage
+
+All brains in your project should import from `../brain.js` instead of `@positronic/core`:
+
+```typescript
+// ✅ DO THIS (from a file in the brains/ directory)
+import { brain } from '../brain.js';
+
+// ❌ NOT THIS
+import { brain } from '@positronic/core';
+```
+
+### Configuring Services
+
+To add project-wide services, modify the `brain.ts` file in the root directory:
+
+```typescript
+import { brain as coreBrain, type Brain } from '@positronic/core';
+
+// Define your services
+interface ProjectServices {
+  logger: {
+    info: (message: string) => void;
+    error: (message: string) => void;
+  };
+  database: {
+    get: (key: string) => Promise<any>;
+    set: (key: string, value: any) => Promise<void>;
+  };
+}
+
+// Export the wrapped brain function
+export function brain<
+  TOptions extends object = object,
+  TState extends object = object
+>(
+  brainConfig: string | { title: string; description?: string }
+): Brain<TOptions, TState, ProjectServices> {
+  return coreBrain<TOptions, TState, ProjectServices>(brainConfig)
+    .withServices({
+      logger: {
+        info: (msg) => console.log(`[<%= '${new Date().toISOString()}' %>] INFO: <%= '${msg}' %>`),
+        error: (msg) => console.error(`[<%= '${new Date().toISOString()}' %>] ERROR: <%= '${msg}' %>`)
+      },
+      database: {
+        get: async (key) => {
+          // Your database implementation
+          return localStorage.getItem(key);
+        },
+        set: async (key, value) => {
+          // Your database implementation
+          localStorage.setItem(key, JSON.stringify(value));
+        }
+      }
+    });
+}
+```
+
+Now all brains automatically have access to these services:
+
+```typescript
+import { brain } from '../brain.js';
+
+export default brain('User Processor')
+  .step('Load User', async ({ logger, database }) => {
+    logger.info('Loading user data');
+    const userData = await database.get('current-user');
+    return { user: userData };
+  });
+```
+
+## Resource Organization
+
+Resources are files that brains can access during execution. Organize them logically:
+
+```
+resources/
+├── prompts/          # AI prompt templates
+│   ├── customer-support.md
+│   └── code-review.md
+├── data/            # Static data files
+│   └── config.json
+└── templates/       # Document templates
+    └── report.md
+```
+
+## Testing Strategy
+
+Keep test files in the `tests/` directory to avoid deployment issues. Tests should:
+- Focus on brain outcomes, not implementation
+- Use mock clients and services
+- Verify the final state and important side effects
+
+See `/docs/brain-testing-guide.md` for detailed testing guidance.
+
+## Development Workflow
+
+1. **Start the development server**: `px server -d`
+2. **Create or modify brains**: Always import from `./brain.js`
+3. **Test locally**: `px brain run <brain-name>`
+4. **Run tests**: `npm test`
+5. **Deploy**: Backend-specific commands (e.g., `px deploy` for Cloudflare)
+
+## Configuration
+
+The `positronic.config.json` file contains project metadata:
+
+```json
+{
+  "projectName": "my-project",
+  "backend": "cloudflare"
+}
+```
+
+## Environment Variables
+
+Use `.env` files for configuration:
+
+```bash
+# API Keys
+ANTHROPIC_API_KEY=your-key-here
+OPENAI_API_KEY=your-key-here
+
+# Backend-specific
+<% if (backend === 'cloudflare') { %>CLOUDFLARE_ACCOUNT_ID=your-account-id
+CLOUDFLARE_API_TOKEN=your-api-token<% } %>
+```
+
+## Best Practices
+
+1. **Services**: Configure once in `brain.ts`, use everywhere
+2. **Resources**: Use for content that non-developers should be able to edit
+3. **Secrets**: Never commit API keys; use environment variables
+4. **Organization**: Group related brains in folders as your project grows
+5. **Testing**: Write tests for critical workflows
+6. **Documentation**: Keep project-specific docs in the `docs/` folder
+
+## Common Patterns
+
+### Logging and Monitoring
+
+```typescript
+// In brain.ts
+interface ProjectServices {
+  metrics: {
+    track: (event: string, properties?: any) => void;
+    time: (label: string) => () => void;
+  };
+}
+
+// In your brain
+export default brain('Analytics Brain')
+  .step('Start Timer', ({ metrics }) => {
+    const endTimer = metrics.time('processing');
+    return { endTimer };
+  })
+  .step('Process', ({ state }) => {
+    // Do work...
+    return state;
+  })
+  .step('End Timer', ({ state, metrics }) => {
+    state.endTimer();
+    metrics.track('processing_complete');
+    return state;
+  });
+```
+
+### API Integration
+
+```typescript
+// In brain.ts
+interface ProjectServices {
+  api: {
+    get: (path: string) => Promise<any>;
+    post: (path: string, data: any) => Promise<any>;
+  };
+}
+
+// Configure with base URL and auth
+const api = {
+  get: async (path: string) => {
+    const response = await fetch(`https://api.example.com<%= '${path}' %>`, {
+      headers: { 'Authorization': `Bearer <%= '${process.env.API_KEY}' %>` }
+    });
+    return response.json();
+  },
+  post: async (path: string, data: any) => {
+    const response = await fetch(`https://api.example.com<%= '${path}' %>`, {
+      method: 'POST',
+      headers: { 
+        'Authorization': `Bearer <%= '${process.env.API_KEY}' %>`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(data)
+    });
+    return response.json();
+  }
+};
+```
+
+## Getting Help
+
+- **Documentation**: https://positronic.dev
+- **CLI Help**: `px --help`
+- **Brain DSL Guide**: `/docs/brain-dsl-guide.md`
+- **Testing Guide**: `/docs/brain-testing-guide.md`