drtrace 0.2.0 → 0.4.0

package/README.md

@@ -23,7 +23,7 @@ This runs an interactive setup wizard that creates the `_drtrace/` configuration
 - Configuration guide (`README.md`)
 - Default agent specification
 
-### Manual Client Integration
+### Node.js Usage
 
 ```typescript
 import { DrTrace } from 'drtrace';
@@ -39,7 +39,6 @@ const client = DrTrace.init();
 //   flushIntervalMs: 1000,
 //   maxRetries: 3,
 //   maxQueueSize: 10000,
-//   timeoutMs: 5000,
 // });
 
 // Attach to console
@@ -50,6 +49,77 @@ console.log('This is captured by DrTrace');
 console.error('Errors are also captured');
 ```
 
+### Browser Usage (React, Vue, etc.)
+
+In browser environments, you must provide `applicationId` and `daemonUrl` explicitly since the browser cannot read config files from the filesystem.
+
+```typescript
+import { DrTrace } from 'drtrace';  // Auto-selects browser entry point
+
+// Browser requires explicit options (no config file loading)
+const client = DrTrace.init({
+  applicationId: 'my-react-app',
+  daemonUrl: 'http://localhost:8001',
+  moduleName: 'frontend',  // Optional: helps identify log source
+  batchSize: 50,
+  flushIntervalMs: 1000,
+});
+
+// Attach to console
+client.attachToConsole();
+
+// Objects are serialized properly
+console.log({ user: 'john', action: 'login' });  // Logs as JSON
+console.error('Something went wrong', new Error('Details'));
+```
+
+**Important for Browser:**
+- `applicationId` is **required** - throws error if missing
+- `daemonUrl` is **required** - throws error if missing
+- CORS must be enabled on the daemon (enabled by default)
+- Objects and errors are automatically serialized to JSON
+
+#### CORS Configuration
+
+The DrTrace daemon allows all origins by default. To restrict origins:
+
+```bash
+# Allow specific origins
+export DRTRACE_CORS_ORIGINS="http://localhost:3000,https://myapp.com"
+
+# Start daemon
+uvicorn drtrace_service.api:app --host localhost --port 8001
+```
+
+## Starting the DrTrace Daemon
+
+**Important**: The DrTrace daemon must be running before your application can send logs.
+
+### Option A: Docker Compose (Recommended)
+
+```bash
+# From the DrTrace repository root
+docker-compose up -d
+
+# Verify it's running
+curl http://localhost:8001/status
+```
+
+### Option B: Native Python Daemon
+
+```bash
+# Set database URL (if using PostgreSQL)
+export DRTRACE_DATABASE_URL="postgresql://postgres:postgres@localhost:5432/drtrace"
+
+# Start the daemon
+uvicorn drtrace_service.api:app --host localhost --port 8001
+
+# In another terminal, verify it's running
+python -m drtrace_service status
+```
+
+**Note**: The daemon runs on `http://localhost:8001` by default. Make sure this matches your `daemonUrl` in the config.
+
 ## Configuration
 
 Configuration is managed via `_drtrace/config.json` created during `npx drtrace init`.
@@ -126,13 +196,13 @@ Create a new DrTrace client instance.
 
 **Options:**
 - `applicationId` (required) - Unique application identifier
-- `daemonUrl` (optional) - DrTrace daemon URL (default: `http://localhost:8001`)
+- `daemonUrl` (required in browser, optional in Node.js) - DrTrace daemon URL (default: `http://localhost:8001`)
+- `moduleName` (optional) - Module/component name for log grouping (default: `'default'`)
 - `enabled` (optional) - Enable/disable DrTrace (default: `true`)
 - `batchSize` (optional) - Batch size for log batching (default: `50`)
 - `flushIntervalMs` (optional) - Flush interval in milliseconds (default: `1000`)
 - `maxRetries` (optional) - Retry attempts for failed sends with exponential backoff (default: `3`)
 - `maxQueueSize` (optional) - Maximum queued log entries before oldest entries are dropped (default: `10000`)
-- `timeoutMs` (optional) - Request timeout per batch in milliseconds (default: `5000`)
 
 ### `client.attachToConsole()`
 

package/agents/CONTRIBUTING.md

@@ -0,0 +1,296 @@
+# Contributing to DrTrace Agents
+
+Thank you for your interest in contributing to DrTrace agents! This guide explains how to create, test, and submit new agents or improvements.
+
+## Creating a New Agent
+
+### 1. File Structure
+
+Create a new agent file named `<agent-name>.md` in this directory:
+
+```
+agents/
+├── <agent-name>.md
+├── log-analysis.md
+├── log-it.md
+├── log-init.md
+├── log-help.md
+└── README.md
+```
+
+### 2. File Format
+
+Use the standardized markdown format with embedded XML:
+
+```markdown
+---
+name: "<agent-name>"
+description: "Brief description of the agent's purpose"
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+\`\`\`xml
+<agent id="<agent-name>.agent.yaml" name="drtrace" title="Agent Title" icon="emoji">
+<activation critical="MANDATORY">
+  <step n="1">First activation step</step>
+  <step n="2">Second activation step</step>
+  ...
+  <rules>
+    <r>Behavior rule 1</r>
+    <r>Behavior rule 2</r>
+  </rules>
+</activation>
+
+<persona>
+  <role>Agent Role</role>
+  <identity>Who the agent is</identity>
+  <communication_style>How the agent communicates</communication_style>
+  <principles>
+    - Principle 1
+    - Principle 2
+  </principles>
+</persona>
+
+<menu title="Menu title">
+  <item cmd="X" hotkey="X" name="Option name">
+    Description of what this option does
+  </item>
+</menu>
+\`\`\`
+
+[Implementation content - patterns, frameworks, examples, etc.]
+```
+
+### 3. Key Components
+
+**Activation Steps** (required):
+- Define how the agent initializes
+- Set persona and rules
+- Display greeting and menu
+- Wait for user input
+- Process commands
+
+**Persona** (required):
+- Role: What the agent does
+- Identity: Who/what the agent is
+- Communication style: Tone and format
+- Principles: Core behavioral guidelines
+
+**Menu** (optional):
+- Interactive commands users can choose
+- Each item has cmd, hotkey, name, description
+- Focus on actionable options, not auto-execution
+
+**Implementation**:
+- Patterns, examples, frameworks
+- Language-specific guidance
+- Copy-paste ready code snippets
+- Decision trees and validation logic
+
+### 4. Multi-Language Support
+
+Agents must support all five languages:
+- Python (stdlib logging, structlog)
+- JavaScript/TypeScript (winston, pino, bunyan)
+- Java (SLF4J, Logback)
+- Go (slog, logrus)
+- C++ (spdlog)
+
+For each language, provide:
+- Pattern examples
+- Library-specific guidance
+- Syntax highlighting
+- Copy-paste ready code
+
+**Example:**
+```markdown
+## Python Pattern
+\`\`\`python
+import logging
+logger = logging.getLogger(__name__)
+logger.info("message")
+\`\`\`
+
+## JavaScript Pattern
+\`\`\`javascript
+const winston = require('winston');
+const logger = winston.createLogger({...});
+logger.info("message");
+\`\`\`
+```
+
+## Testing Your Agent
+
+### 1. Manual Testing
+
+**In Python:**
+```bash
+cd /path/to/project
+python -m drtrace_service init-agent --agent <agent-name>
+cat _drtrace/agents/<agent-name>.md
+```
+
+**In JavaScript:**
+```bash
+cd /path/to/project
+npx drtrace init-agent --agent <agent-name>
+cat _drtrace/agents/<agent-name>.md
+```
+
+**In C++:**
+```bash
+cd /path/to/project
+drtrace init-agent --agent <agent-name>
+cat _drtrace/agents/<agent-name>.md
+```
+
+### 2. Activation Testing
+
+Load the agent in your preferred AI chat or IDE:
+1. Copy the entire agent file content
+2. Paste into the chat interface
+3. Wait for the greeting and menu
+4. Verify all menu options work
+5. Test core workflows
+
+### 3. Edge Cases
+
+Test your agent with:
+- Empty input
+- Malformed code
+- Very large code samples
+- Multiple programming languages
+- Missing context (ask for clarification)
+- Ambiguous requests (offer options)
+
+### 4. Automated Testing
+
+Agents are tested via:
+- **Unit tests**: Agent spec syntax validation
+- **Integration tests**: Agent loading across ecosystems
+- **E2E tests**: Agent activation and menu interaction
+
+## Updating Existing Agents
+
+When updating an existing agent:
+
+1. **Backward Compatibility**: Maintain the same persona and core menu items
+2. **Documentation**: Update `agents/README.md` if functionality changes
+3. **Testing**: Run full test suite before submitting
+4. **Version Notes**: Add comment in agent file about what changed
+
+Example:
+```markdown
+---
+name: "log-analysis"
+description: "Log Analysis Agent"
+version: "1.1.0"
+updated: "2025-12-22"
+changelog: "Added support for cross-service log correlation"
+---
+```
+
+## Submission Checklist
+
+Before submitting your agent:
+
+- [ ] File named `<agent-name>.md`
+- [ ] YAML frontmatter with name and description
+- [ ] XML activation block with 9+ steps
+- [ ] Persona definition (role, identity, communication_style, principles)
+- [ ] Interactive menu with 3+ options
+- [ ] Examples for all 5 supported languages
+- [ ] Copy-paste ready code snippets
+- [ ] Tested in Python, JavaScript, C++ ecosystems
+- [ ] No hardcoded file paths or system-specific code
+- [ ] Error handling for edge cases
+- [ ] Markdown syntax verified (no broken links)
+- [ ] README.md updated (if adding new agent)
+
+## Code Guidelines
+
+### Do's ✅
+- Use lazy string formatting (f-strings, template literals)
+- Validate user input before processing
+- Ask for clarification if context is unclear
+- Provide helpful error messages
+- Include multiple examples
+- Support natural language queries
+- Offer copy-paste ready code
+
+### Don'ts ❌
+- Don't hardcode system paths
+- Don't assume user's environment
+- Don't execute code automatically (wait for confirmation)
+- Don't log sensitive data
+- Don't make breaking changes to existing agents
+- Don't use platform-specific syntax
+- Don't skip error handling
+
+## File Size Guidelines
+
+Agent files should be:
+- **Minimal**: 200-500 lines for simple agents
+- **Comprehensive**: 800-1500 lines for complex agents
+- **Maximum**: 2000 lines (split into multiple agents if larger)
+
+Avoid:
+- Excessive repetition
+- Redundant examples
+- Over-documentation
+- Unnecessary complexity
+
+## Directory Structure
+
+After your contribution:
+
+```
+agents/
+├── <agent-name>.md            ← Your new agent
+├── log-analysis.md            ← Existing
+├── log-it.md                  ← Existing
+├── log-init.md                ← Existing
+├── log-help.md                ← Existing
+├── README.md                  ← Updated
+└── CONTRIBUTING.md            ← This file
+```
+
+## Distribution Pipeline
+
+1. **Development**: Agent file created in `agents/`
+2. **Testing**: Tested across ecosystems
+3. **Packaging**: Included in PyPI, npm, C++ releases
+4. **Deployment**: Users get agent via `pip install drtrace`, `npm install drtrace`, etc.
+5. **Activation**: Users run `drtrace init-agent --agent <name>`
+
+## Questions?
+
+Refer to:
+- [log-analysis.md](log-analysis.md) — Complete working example
+- [log-it.md](log-it.md) — Another example with 5-criteria validation
+- [Agent Implementation Guide](../_bmad-output/implementation-artifacts/log-it-agent-implementation-guide.md)
+- [Agent Refactoring Plan](../_bmad-output/implementation-artifacts/agent-files-shared-resource-refactoring-plan.md)
+
+## Review Process
+
+1. **Submit**: Create PR with new/updated agent file
+2. **Review**: Architecture team reviews for:
+   - Correctness and completeness
+   - Multi-language support
+   - Edge case handling
+   - Documentation quality
+3. **Feedback**: Comments provided; iterate as needed
+4. **Approval**: Merged to main branch
+5. **Release**: Published with next version
+
+---
+
+**Agent Quality Standards**
+- All agents must be production-ready
+- Must support all 5 programming languages
+- Must include comprehensive documentation
+- Must handle edge cases gracefully
+- Must provide value to developers
+
+Thank you for contributing to DrTrace! 🚀

package/agents/README.md

@@ -0,0 +1,174 @@
+# DrTrace Agent Library
+
+Central repository for all DrTrace interactive agents. These agents guide developers through code analysis, logging decisions, and troubleshooting workflows.
+
+## Agents
+
+### log-analysis (Log Analysis Specialist)
+Analyzes application logs and provides root-cause explanations for errors.
+
+- **Purpose**: Help developers understand why errors occurred with AI-powered analysis
+- **Input**: Natural language queries about log data and time windows
+- **Output**: Structured markdown reports with summaries, root causes, evidence, and suggested fixes
+- **Availability**: All ecosystems (Python, JavaScript, C++)
+
+**Activate:**
+```bash
+# Python
+python -m drtrace_service init-agent --agent log-analysis
+
+# JavaScript
+npx drtrace init-agent --agent log-analysis
+
+# C++
+drtrace init-agent --agent log-analysis
+```
+
+### log-it (Strategic Logging Assistant)
+Helps developers add efficient, strategic logging to their code.
+
+- **Purpose**: Guide developers through logging decisions using 5-criteria validation
+- **Input**: Function or file code to analyze
+- **Output**: Strategic logging suggestions with line numbers, log levels, and copy-paste ready code
+- **Availability**: All ecosystems (Python, JavaScript, Java, Go, C++)
+
+**Activate:**
+```bash
+# Python
+python -m drtrace_service init-agent --agent log-it
+
+# JavaScript
+npx drtrace init-agent --agent log-it
+
+# C++
+drtrace init-agent --agent log-it
+```
+
+### log-init (DrTrace Setup Assistant)
+Analyzes your project structure and suggests language-specific DrTrace setup.
+
+- **Purpose**: Inspect real project files (Python, C++, JS/TS) and recommend minimal, best‑practice integration points.
+- **Input**: Project root path and/or key files (e.g., `main.py`, `CMakeLists.txt`, `package.json`).
+- **Output**: Markdown suggestions with integration points, code snippets, config changes, and verification steps.
+
+**Activate:**
+
+```bash
+# Python
+python -m drtrace_service init-agent --agent log-init
+
+# JavaScript
+npx drtrace init-agent --agent log-init
+
+# C++
+drtrace init-agent --agent log-init
+```
+
+See `docs/log-init-agent-guide.md` for detailed usage, examples, and how it works with `init-project`.
+
+### log-help (DrTrace Setup Guide)
+Provides interactive, step-by-step guidance and troubleshooting for DrTrace setup.
+
+- **Purpose**: Walk you through setup steps for each language and help debug common issues.
+- **Input**: Natural language requests (e.g., “start Python setup guide”, “I’m stuck – daemon not connecting”).
+- **Output**: Guided checklists, progress tracking, and troubleshooting instructions.
+
+**Activate:**
+
+```bash
+# Python
+python -m drtrace_service init-agent --agent log-help
+
+# JavaScript
+npx drtrace init-agent --agent log-help
+
+# C++
+drtrace init-agent --agent log-help
+```
+
+See `docs/log-help-agent-guide.md` for guidance on step-by-step usage and troubleshooting patterns.
+
+## Usage
+
+1. **Bootstrap an agent into your project:**
+   ```bash
+   drtrace init-agent --agent <agent-name>
+   ```
+   This creates `_drtrace/agents/<agent-name>.md` in your project.
+
+2. **Activate an agent in your chat/IDE:**
+   - Load the agent file from `_drtrace/agents/<agent-name>.md`
+   - Or use `@agent-name` shorthand if supported by your host
+
+3. **Interact with the agent:**
+   - Follow the agent's menu options
+   - Provide code or query details as requested
+   - Use the agent's structured responses for your work
+
+## Supported Languages
+
+All agents support analysis and suggestions for:
+- **Python** (stdlib logging, structlog)
+- **JavaScript/TypeScript** (winston, pino, bunyan)
+- **Java** (SLF4J, Logback)
+- **Go** (slog, logrus)
+- **C++** (spdlog)
+
+## File Format
+
+Agents use a standardized markdown format with embedded XML configuration:
+
+```
+---
+name: "agent-name"
+description: "Agent description"
+---
+
+[XML activation instructions and persona definition]
+
+[Agent implementation content]
+```
+
+Key sections:
+- `<agent>` tag: Identifies the agent and its capabilities
+- `<activation>`: Step-by-step instructions for activation
+- `<rules>`: Behavioral guidelines
+- `<persona>`: Role definition and communication style
+- `<menu>`: Interactive menu items (optional)
+
+See [log-analysis.md](log-analysis.md) or [log-it.md](log-it.md) for complete examples.
+
+## Distribution
+
+Agents are distributed with each ecosystem:
+
+- **Python**: Packaged in `drtrace_service.resources.agents` via pip
+- **JavaScript**: Copied to `node_modules/drtrace/agents/` via npm
+- **C++**: Installed alongside library via package manager
+
+When you run `drtrace init-agent`, the agent spec is copied from the installed package location to your local project at `_drtrace/agents/`.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on:
+- Creating new agents
+- Testing agents across ecosystems
+- Updating existing agents
+- Documentation requirements
+
+## Maintenance
+
+- **Version sync**: Agent files are versioned with each DrTrace release
+- **Updates**: Agents are updated in main branch; new versions published with releases
+- **Compatibility**: All agents must work across Python, JavaScript, and C++ ecosystems
+
+## References
+
+- [Agent Implementation Guide](../_bmad-output/implementation-artifacts/log-it-agent-implementation-guide.md)
+- [Agent Refactoring Plan](../_bmad-output/implementation-artifacts/agent-files-shared-resource-refactoring-plan.md)
+- [DrTrace Documentation](../docs/overview.md)
+
+---
+
+**Last Updated**: December 29, 2025  
+**Maintainer**: DrTrace Architecture Team