drtrace 0.3.0 → 0.5.0

package/agents/log-help.md

@@ -11,7 +11,7 @@ You must fully embody this agent's persona and follow all activation instruction
   <step n="1">Load persona from this current agent file (already in context)</step>
   <step n="2">Remember: You are a Setup Guide Assistant for DrTrace</step>
   <step n="3">Your primary mission is to walk users through DrTrace setup step-by-step using the help APIs and setup guide, not to guess or skip steps</step>
-  <step n="4">ALWAYS prefer Method 1 (Python help APIs) → then Method 2 (HTTP help endpoints) → then Method 3 (CLI) in that exact order</step>
+  <step n="4">When processing a user query, check `agents/daemon-method-selection.md` for details.</step>
   <step n="5">For each user interaction, clearly state the current step, what to do next, and how to verify it worked</step>
   <step n="6">When calling help APIs, use:
     - `start_setup_guide(language, project_root)` to begin or restart a guide
@@ -32,7 +32,7 @@ You must fully embody this agent's persona and follow all activation instruction
     <r>NEVER skip verification or pretend steps are complete; use the setup guide and help APIs as the source of truth</r>
     <r>ALWAYS explain what you are doing when progressing steps or troubleshooting issues</r>
     <r>Display menu items exactly as defined in the menu section and in the order given</r>
-    <r>Prefer Python APIs, then HTTP endpoints, then CLI in that order; explain fallbacks when switching methods</r>
+    <r>Prefer HTTP/curl, then Python SDK, then CLI in that order; explain fallbacks when switching methods</r>
   </rules>
 </activation>
 
@@ -50,6 +50,10 @@ You must fully embody this agent's persona and follow all activation instruction
   </principles>
 </persona>
 
+## CLI Availability & Filters
+
+See [agents/daemon-method-selection.md](agents/daemon-method-selection.md) for CLI availability guidance and the mutually exclusive `message_contains` vs `message_regex` rule (includes CLI/HTTP examples).
+
 <menu title="How can I guide your DrTrace setup?">
   <item cmd="S" hotkey="S" name="Start setup guide">
     Begin or restart the step-by-step setup guide for a specific language.
@@ -92,83 +96,6 @@ You must fully embody this agent's persona and follow all activation instruction
 </agent>
 ```
 
-## How to Use DrTrace Help APIs
-
-**Reference**: See `agents/daemon-method-selection.md` for complete method selection guide.
-
-**Priority Order**: HTTP/curl (preferred) → Python SDK → CLI (last resort)
-
-### Quick Reference: Help API Operations
-
-| Operation | HTTP (Preferred) | Python SDK |
-|-----------|------------------|------------|
-| Start guide | `POST /help/guide/start` | `start_setup_guide(language, project_root)` |
-| Current step | `GET /help/guide/current` | `get_current_step(project_root)` |
-| Complete step | `POST /help/guide/complete` | `complete_step(step_number, project_root)` |
-| Troubleshoot | `POST /help/troubleshoot` | `troubleshoot(issue, project_root)` |
-
-### HTTP/curl Examples (Preferred)
-
-```bash
-# Start setup guide
-curl -X POST http://localhost:8001/help/guide/start \
-  -H "Content-Type: application/json" \
-  -d '{"language": "python", "project_root": "/path/to/project"}'
-
-# Get current step
-curl "http://localhost:8001/help/guide/current?project_root=/path/to/project"
-
-# Mark step complete
-curl -X POST http://localhost:8001/help/guide/complete \
-  -H "Content-Type: application/json" \
-  -d '{"step_number": 1, "project_root": "/path/to/project"}'
-
-# Troubleshoot
-curl -X POST http://localhost:8001/help/troubleshoot \
-  -H "Content-Type: application/json" \
-  -d '{"issue": "daemon not connecting", "project_root": "/path/to/project"}'
-```
-
-### Python SDK Examples (Fallback)
-
-```python
-from pathlib import Path
-from drtrace_service.help_agent_interface import (
-    start_setup_guide,
-    get_current_step,
-    complete_step,
-    troubleshoot,
-)
-import asyncio
-
-project_root = Path(".")
-
-# Start guide
-guide = await start_setup_guide(language="python", project_root=project_root)
-
-# Get current step
-current = await get_current_step(project_root=project_root)
-
-# Complete step
-next_step = await complete_step(step_number=1, project_root=project_root)
-
-# Troubleshoot
-help_text = await troubleshoot("daemon not connecting", project_root=project_root)
-
-# Non-async context
-guide = asyncio.run(start_setup_guide(language="python", project_root=project_root))
-```
-
-### Fallback Strategy
-
-1. **HTTP/curl (Preferred)**: Simple, no dependencies, works everywhere
-2. **Python SDK (Fallback)**: Rich async features when HTTP unavailable
-3. **CLI (Last Resort)**: `python -m drtrace_service help guide ...`
-
-**Important**: Always fetch `/openapi.json` first when using HTTP to discover correct endpoints and field names.
-
-See `agents/daemon-method-selection.md` for complete fallback implementation.
-
 ## Activation Instructions
 
 To activate the `log-help` agent in a project:

package/agents/log-init.md

@@ -30,6 +30,10 @@ You must fully embody this agent's persona and follow all activation instruction
 </activation>
 
 <persona>
+
+## CLI Availability & Filters
+
+See [agents/daemon-method-selection.md](agents/daemon-method-selection.md) for CLI availability guidance and the mutually exclusive `message_contains` vs `message_regex` rule (includes CLI/HTTP examples).
   <role>Setup Specialist</role>
   <identity>Expert at analyzing project structures and suggesting intelligent DrTrace integration. Reads source files directly to understand project organization, build systems, and existing logging. Provides language-specific setup suggestions with minimal impact on existing code.</identity>
   <communication_style>Clear and educational. Reads and analyzes project files before suggesting setup. Explains reasoning for each suggestion. Provides structured responses with code examples. Ensures suggestions are non-destructive and compatible with existing setup.</communication_style>

package/agents/log-it.md

@@ -52,6 +52,10 @@ You must fully embody this agent's persona and follow all activation instruction
   </principles>
 </persona>
 
+## CLI Availability & Filters
+
+See [agents/daemon-method-selection.md](agents/daemon-method-selection.md) for CLI availability guidance and the mutually exclusive `message_contains` vs `message_regex` rule (includes CLI/HTTP examples).
+
 <menu title="What can I help you log?">
   <item cmd="L" hotkey="L" name="Log this function">
     Analyze a specific function and suggest strategic logging points.

package/bin/cli.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+
+/**
+ * CLI entry point for drtrace commands
+ * This wrapper is copied to dist/bin/cli.js and imports from compiled TypeScript
+ */
+
+const path = require('path');
+
+// Resolve paths relative to the dist directory
+// When copied to dist/bin/cli.js, we need to go up one level to access dist/cli/*
+const { runGrep } = require(path.join(__dirname, '..', 'cli', 'grep'));
+const { runStatus } = require(path.join(__dirname, '..', 'cli', 'status'));
+const { runInitProject } = require(path.join(__dirname, '..', 'init'));
+
+const COMMANDS = ['grep', 'status', 'init'];
+
+function printMainHelp() {
+  console.log(`Usage: drtrace <command> [options]
+
+Commands:
+  grep      Search log messages with pattern matching
+  status    Check daemon health and configuration
+  init      Initialize DrTrace project configuration
+
+Options:
+  -h, --help     Show this help message
+  -v, --version  Show version number
+
+Examples:
+  drtrace status
+  drtrace grep "error"
+  drtrace grep -E "error|warning" --since 30m
+  drtrace init
+
+For command-specific help:
+  drtrace <command> --help
+`);
+}
+
+function printVersion() {
+  const packageJson = require(path.join(__dirname, '..', '..', 'package.json'));
+  console.log(`drtrace v${packageJson.version}`);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  
+  if (args.length === 0) {
+    printMainHelp();
+    return 0;
+  }
+  
+  const firstArg = args[0];
+  
+  // Handle global flags
+  if (firstArg === '-h' || firstArg === '--help') {
+    printMainHelp();
+    return 0;
+  }
+  
+  if (firstArg === '-v' || firstArg === '--version') {
+    printVersion();
+    return 0;
+  }
+  
+  // Route to command
+  const command = firstArg;
+  const commandArgs = args.slice(1);
+  
+  switch (command) {
+    case 'grep':
+      return await runGrep(commandArgs);
+    
+    case 'status':
+      return await runStatus(commandArgs);
+    
+    case 'init':
+      const projectRoot = commandArgs.find((arg, i) => 
+        (args[i - 1] === '--project-root' || args[i - 1] === '-p')
+      );
+      return await runInitProject(projectRoot);
+    
+    default:
+      console.error(`Error: Unknown command '${command}'`);
+      console.error('');
+      printMainHelp();
+      return 2;
+  }
+}
+
+// Run CLI
+main().then((exitCode) => {
+  process.exit(exitCode);
+}).catch((error) => {
+  console.error(`Fatal error: ${error.message}`);
+  process.exit(1);
+});

package/dist/bin/cli.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+
+/**
+ * CLI entry point for drtrace commands
+ * This wrapper is copied to dist/bin/cli.js and imports from compiled TypeScript
+ */
+
+const path = require('path');
+
+// Resolve paths relative to the dist directory
+// When copied to dist/bin/cli.js, we need to go up one level to access dist/cli/*
+const { runGrep } = require(path.join(__dirname, '..', 'cli', 'grep'));
+const { runStatus } = require(path.join(__dirname, '..', 'cli', 'status'));
+const { runInitProject } = require(path.join(__dirname, '..', 'init'));
+
+const COMMANDS = ['grep', 'status', 'init'];
+
+function printMainHelp() {
+  console.log(`Usage: drtrace <command> [options]
+
+Commands:
+  grep      Search log messages with pattern matching
+  status    Check daemon health and configuration
+  init      Initialize DrTrace project configuration
+
+Options:
+  -h, --help     Show this help message
+  -v, --version  Show version number
+
+Examples:
+  drtrace status
+  drtrace grep "error"
+  drtrace grep -E "error|warning" --since 30m
+  drtrace init
+
+For command-specific help:
+  drtrace <command> --help
+`);
+}
+
+function printVersion() {
+  const packageJson = require(path.join(__dirname, '..', '..', 'package.json'));
+  console.log(`drtrace v${packageJson.version}`);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  
+  if (args.length === 0) {
+    printMainHelp();
+    return 0;
+  }
+  
+  const firstArg = args[0];
+  
+  // Handle global flags
+  if (firstArg === '-h' || firstArg === '--help') {
+    printMainHelp();
+    return 0;
+  }
+  
+  if (firstArg === '-v' || firstArg === '--version') {
+    printVersion();
+    return 0;
+  }
+  
+  // Route to command
+  const command = firstArg;
+  const commandArgs = args.slice(1);
+  
+  switch (command) {
+    case 'grep':
+      return await runGrep(commandArgs);
+    
+    case 'status':
+      return await runStatus(commandArgs);
+    
+    case 'init':
+      const projectRoot = commandArgs.find((arg, i) => 
+        (args[i - 1] === '--project-root' || args[i - 1] === '-p')
+      );
+      return await runInitProject(projectRoot);
+    
+    default:
+      console.error(`Error: Unknown command '${command}'`);
+      console.error('');
+      printMainHelp();
+      return 2;
+  }
+}
+
+// Run CLI
+main().then((exitCode) => {
+  process.exit(exitCode);
+}).catch((error) => {
+  console.error(`Fatal error: ${error.message}`);
+  process.exit(1);
+});

package/dist/browser.d.ts

@@ -0,0 +1,28 @@
+import type { ClientOptions, LogLevel } from './types';
+/**
+ * DrTrace client for browser environments.
+ *
+ * Unlike the Node.js client, this does NOT load configuration from files.
+ * All options must be passed explicitly to init().
+ */
+export declare class DrTrace {
+    private queue;
+    private logger;
+    private enabled;
+    private constructor();
+    /**
+     * Initialize DrTrace for browser environments.
+     * Unlike Node.js, browser does not load config from files.
+     * All options must be passed explicitly.
+     *
+     * @param opts - Client options (applicationId and daemonUrl are required)
+     * @throws Error if applicationId or daemonUrl are not provided
+     */
+    static init(opts: ClientOptions): DrTrace;
+    attachToConsole(): void;
+    detachFromConsole(): void;
+    log(message: string, level?: LogLevel, context?: Record<string, unknown>): void;
+    error(message: string, context?: Record<string, unknown>): void;
+    shutdown(): Promise<void>;
+}
+export * from './types';

package/dist/browser.js

@@ -0,0 +1,91 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DrTrace = void 0;
+const transport_1 = require("./transport");
+const queue_1 = require("./queue");
+const logger_1 = require("./logger");
+/**
+ * DrTrace client for browser environments.
+ *
+ * Unlike the Node.js client, this does NOT load configuration from files.
+ * All options must be passed explicitly to init().
+ */
+class DrTrace {
+    constructor(opts) {
+        const transport = new transport_1.Transport({
+            daemonUrl: opts.daemonUrl,
+            maxRetries: opts.maxRetries ?? 3,
+            timeoutMs: 5000,
+        });
+        this.queue = new queue_1.LogQueue({
+            transport,
+            batchSize: opts.batchSize ?? 50,
+            flushIntervalMs: opts.flushIntervalMs ?? 1000,
+            maxQueueSize: opts.maxQueueSize ?? 10000,
+        });
+        this.queue.start();
+        this.enabled = opts.enabled ?? true;
+        this.logger = new logger_1.DrTraceLogger({
+            queue: this.queue,
+            applicationId: opts.applicationId,
+            moduleName: opts.moduleName,
+            logLevel: (opts.logLevel ?? 'info'),
+        });
+    }
+    /**
+     * Initialize DrTrace for browser environments.
+     * Unlike Node.js, browser does not load config from files.
+     * All options must be passed explicitly.
+     *
+     * @param opts - Client options (applicationId and daemonUrl are required)
+     * @throws Error if applicationId or daemonUrl are not provided
+     */
+    static init(opts) {
+        if (!opts.applicationId) {
+            throw new Error('applicationId is required for browser usage');
+        }
+        if (!opts.daemonUrl) {
+            throw new Error('daemonUrl is required for browser usage');
+        }
+        return new DrTrace(opts);
+    }
+    attachToConsole() {
+        if (!this.enabled)
+            return;
+        this.logger.attachToConsole();
+    }
+    detachFromConsole() {
+        this.logger.detachFromConsole();
+    }
+    log(message, level = 'info', context) {
+        if (!this.enabled)
+            return;
+        this.logger.log(level, message, context);
+    }
+    error(message, context) {
+        if (!this.enabled)
+            return;
+        this.logger.log('error', message, context);
+    }
+    async shutdown() {
+        await this.queue.flush();
+        this.queue.stop();
+        this.detachFromConsole();
+    }
+}
+exports.DrTrace = DrTrace;
+__exportStar(require("./types"), exports);

package/dist/cli/grep.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Grep command implementation for searching logs with POSIX regex.
+ * Matches Python implementation in packages/python/src/drtrace_service/cli/grep.py
+ */
+interface GrepOptions {
+    pattern: string;
+    ignoreCase?: boolean;
+    count?: boolean;
+    invertMatch?: boolean;
+    lineNumber?: boolean;
+    extendedRegex?: boolean;
+    since?: string;
+    applicationId?: string;
+    daemonHost?: string;
+    daemonPort?: number;
+    json?: boolean;
+    color?: 'auto' | 'always' | 'never';
+}
+/**
+ * Main grep implementation
+ */
+export declare function grep(options: GrepOptions): Promise<number>;
+/**
+ * Parse CLI arguments and run grep command
+ */
+export declare function runGrep(args: string[]): Promise<number>;
+export {};