noctrace 0.8.2 → 1.0.0

package/README.md

@@ -87,6 +87,7 @@ Requires Node.js 20+. Optional `--install-hooks` flag enables real-time hook eve
 - **API Error Markers** — rate limit, billing, and auth failures appear as full-width red alert banners on the timeline
 - **Agent Teams Panel** — detects running Agent Teams at `~/.claude/teams/`, shows members and task counts in a flyout
 - **Context Startup Flyout** — shows which instruction files (CLAUDE.md and others) loaded at session start with estimated token counts, parsed from JSONL system records
+- **Docker Support** — `npx noctrace --docker <container>` attaches to a running Docker container, injects a lightweight watcher, and streams JSONL events back to your host in real time. Zero container setup required
 
 ![Noctrace waterfall timeline](docs/screenshots/noctrace-waterfall.gif)
 
@@ -141,6 +142,7 @@ No config files. No cloud. Everything stays local. Optional hooks for richer rea
 
 | CLI Flag | Description |
 |----------|-------------|
+| `--docker <container>` | Attach to a running Docker container and stream its Claude Code sessions back to your host. Zero container setup |
 | `--install-hooks` | Configure Claude Code to push real-time events to noctrace |
 | `--uninstall-hooks` | Remove noctrace hooks from Claude Code |
 

package/bin/docker-watcher.sh

@@ -0,0 +1,108 @@
+#!/bin/sh
+# Noctrace Docker Watcher — injected into containers to stream JSONL to host.
+# Usage: docker-watcher.sh <claude_dir> <noctrace_url> <container_name>
+# Streams JSONL lines via curl POST to the noctrace /api/docker/stream endpoint.
+# Sends heartbeats every 10 seconds to /api/docker/heartbeat.
+
+CLAUDE_DIR="$1"
+NOCTRACE_URL="$2"
+CONTAINER_NAME="$3"
+PROJECTS_DIR="$CLAUDE_DIR/projects"
+
+if [ -z "$CLAUDE_DIR" ] || [ -z "$NOCTRACE_URL" ] || [ -z "$CONTAINER_NAME" ]; then
+  echo "Usage: docker-watcher.sh <claude_dir> <noctrace_url> <container_name>" >&2
+  exit 1
+fi
+
+# Track watched files to avoid duplicate tail processes
+WATCHED="/tmp/.noctrace-watched-$$"
+PIDS="/tmp/.noctrace-pids-$$"
+touch "$WATCHED" "$PIDS"
+
+cleanup() {
+  # Kill all tail processes we started
+  while IFS= read -r pid; do
+    kill "$pid" 2>/dev/null
+  done < "$PIDS"
+  rm -f "$WATCHED" "$PIDS"
+  exit 0
+}
+
+trap cleanup TERM INT
+
+# Detect HTTP client
+if command -v curl >/dev/null 2>&1; then
+  HTTP_CMD="curl"
+elif command -v wget >/dev/null 2>&1; then
+  HTTP_CMD="wget"
+else
+  echo "[noctrace-watcher] Neither curl nor wget found in container" >&2
+  exit 1
+fi
+
+post_stream() {
+  file="$1"
+  if [ "$HTTP_CMD" = "curl" ]; then
+    curl -s -X POST "$NOCTRACE_URL/api/docker/stream" \
+      -H "Content-Type: text/plain" \
+      -H "X-Container-Name: $CONTAINER_NAME" \
+      -H "X-Container-Path: $file" \
+      --data-binary @- || true
+  else
+    wget -q -O /dev/null --post-file=- \
+      --header="Content-Type: text/plain" \
+      --header="X-Container-Name: $CONTAINER_NAME" \
+      --header="X-Container-Path: $file" \
+      "$NOCTRACE_URL/api/docker/stream" 2>/dev/null || true
+  fi
+}
+
+post_heartbeat() {
+  if [ "$HTTP_CMD" = "curl" ]; then
+    curl -s -X POST "$NOCTRACE_URL/api/docker/heartbeat" \
+      -H "X-Container-Name: $CONTAINER_NAME" || true
+  else
+    wget -q -O /dev/null --post-data="" \
+      --header="X-Container-Name: $CONTAINER_NAME" \
+      "$NOCTRACE_URL/api/docker/heartbeat" 2>/dev/null || true
+  fi
+}
+
+watch_file() {
+  file="$1"
+  # Send full file content then follow new lines
+  tail -f -n +1 "$file" 2>/dev/null | while IFS= read -r line; do
+    printf '%s\n' "$line" | post_stream "$file"
+  done &
+  echo $! >> "$PIDS"
+  echo "$file" >> "$WATCHED"
+}
+
+# Initial scan — watch all existing JSONL files
+if [ -d "$PROJECTS_DIR" ]; then
+  find "$PROJECTS_DIR" -name "*.jsonl" -type f 2>/dev/null | while IFS= read -r f; do
+    watch_file "$f"
+  done
+fi
+
+# Main loop: scan for new files + send heartbeat
+HEARTBEAT_COUNTER=0
+while true; do
+  sleep 3
+
+  # Scan for new JSONL files (including subagents)
+  if [ -d "$PROJECTS_DIR" ]; then
+    find "$PROJECTS_DIR" -name "*.jsonl" -type f 2>/dev/null | while IFS= read -r f; do
+      if ! grep -qxF "$f" "$WATCHED" 2>/dev/null; then
+        watch_file "$f"
+      fi
+    done
+  fi
+
+  # Heartbeat every ~10 seconds (3s sleep * 3 iterations)
+  HEARTBEAT_COUNTER=$((HEARTBEAT_COUNTER + 1))
+  if [ "$HEARTBEAT_COUNTER" -ge 3 ]; then
+    post_heartbeat
+    HEARTBEAT_COUNTER=0
+  fi
+done

package/bin/noctrace-mcp.js

@@ -20,9 +20,14 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
 
-const VERSION = '0.5.1';
-const NOCTRACE_PORT = 4117;
-const BASE_URL = `http://localhost:${NOCTRACE_PORT}`;
+const VERSION = '0.9.0';
+const NOCTRACE_PORT = parseInt(process.env.NOCTRACE_PORT ?? '4117', 10);
+
+// Validate NOCTRACE_HOST: only allow localhost, 127.0.0.1, and host.docker.internal
+const rawHost = process.env.NOCTRACE_HOST ?? 'localhost';
+const ALLOWED_HOSTS = ['localhost', '127.0.0.1', 'host.docker.internal'];
+const NOCTRACE_HOST = ALLOWED_HOSTS.includes(rawHost) ? rawHost : 'localhost';
+const BASE_URL = `http://${NOCTRACE_HOST}:${NOCTRACE_PORT}`;
 
 // ---------------------------------------------------------------------------
 // Session path discovery
@@ -71,26 +76,56 @@ async function newestJsonl(dir) {
   return newest;
 }
 
+/**
+ * Translate a container-internal path to the host-side path.
+ * Uses NOCTRACE_PATH_MAP env var: "container_prefix:host_prefix"
+ * Example: NOCTRACE_PATH_MAP="/root/.claude:/Users/lam/.claude"
+ *
+ * @param {string} containerPath
+ * @returns {string}
+ */
+function translatePath(containerPath) {
+  const pathMap = process.env.NOCTRACE_PATH_MAP;
+  if (!pathMap) return containerPath;
+  const sep = pathMap.indexOf(':');
+  if (sep === -1) return containerPath;
+  const containerPrefix = pathMap.slice(0, sep);
+  const hostPrefix = pathMap.slice(sep + 1);
+  if (containerPath.startsWith(containerPrefix)) {
+    const translated = hostPrefix + containerPath.slice(containerPrefix.length);
+    // Validate no path traversal: resolved path must stay under hostPrefix
+    const resolved = path.resolve(translated);
+    if (!resolved.startsWith(path.resolve(hostPrefix) + path.sep) && resolved !== path.resolve(hostPrefix)) {
+      process.stderr.write(`[noctrace-mcp] Path traversal blocked: ${containerPath}\n`);
+      return containerPath;
+    }
+    return translated;
+  }
+  return containerPath;
+}
+
 /**
  * Discover the JSONL session path for the current Claude Code session.
+ * Returns the host-translated path when NOCTRACE_PATH_MAP is set.
  *
  * @returns {Promise<string|null>}
  */
 async function discoverSessionPath() {
   // Option a: direct env var
   if (process.env.CLAUDE_SESSION_PATH) {
-    return process.env.CLAUDE_SESSION_PATH;
+    return translatePath(process.env.CLAUDE_SESSION_PATH);
   }
 
   // Option b: derive from project directory
   const projectDir = process.env.CLAUDE_PROJECT_DIR ?? process.env.PWD ?? null;
   if (!projectDir) return null;
 
-  const claudeHome = process.env.CLAUDE_HOME ?? path.join(os.homedir(), '.claude');
+  const claudeHome = process.env.CLAUDE_CONFIG_DIR ?? process.env.CLAUDE_HOME ?? path.join(os.homedir(), '.claude');
   const slug = pathToSlug(projectDir);
   const projectSessionDir = path.join(claudeHome, 'projects', slug);
 
-  return newestJsonl(projectSessionDir);
+  const sessionPath = await newestJsonl(projectSessionDir);
+  return sessionPath ? translatePath(sessionPath) : null;
 }
 
 // ---------------------------------------------------------------------------
@@ -149,7 +184,7 @@ async function postSessionAction(action, sessionPath) {
   return new Promise((resolve) => {
     const req = http.request(
       {
-        hostname: 'localhost',
+        hostname: NOCTRACE_HOST,
         port: NOCTRACE_PORT,
         path: `/api/sessions/${action}`,
         method: 'POST',
@@ -254,10 +289,14 @@ function handleMessage(line) {
 async function main() {
   let sessionPath = await discoverSessionPath();
 
+  // When running inside Docker (NOCTRACE_HOST != localhost), skip server start —
+  // the noctrace server runs on the host, not inside the container.
+  const isRemote = NOCTRACE_HOST !== 'localhost' && NOCTRACE_HOST !== '127.0.0.1';
+
   // Check if noctrace is already running; if not, start it (first MCP process wins).
   // Use a retry loop to handle the race where two MCP processes start simultaneously.
   const running = await isServerRunning();
-  if (!running) {
+  if (!running && !isRemote) {
     process.stderr.write('[noctrace-mcp] Starting noctrace server...\n');
     try {
       await startNoctraceServer();

package/bin/noctrace.js

@@ -197,6 +197,129 @@ if (args.includes('--disable')) {
   process.exit(0);
 }
 
+if (args.includes('--docker')) {
+  const containerArg = args[args.indexOf('--docker') + 1];
+  if (!containerArg || containerArg.startsWith('--')) {
+    console.error('[noctrace] Usage: npx noctrace --docker <container-name-or-id>');
+    console.error('[noctrace] Example: npx noctrace --docker my-claude-container');
+    process.exit(1);
+  }
+
+  const {
+    isValidContainerName,
+    assertContainerRunning,
+    resolveClaudeDir,
+    detectHttpTool,
+    resolveHostUrl,
+    copyWatcherScript,
+    spawnWatcher,
+    cleanupWatcher,
+    defaultDockerRunner,
+  } = await import('../dist/server/server/docker.js');
+
+  const { readFileSync, writeFileSync, unlinkSync } = await import('node:fs');
+
+  // Validate container name to prevent command injection
+  if (!isValidContainerName(containerArg)) {
+    console.error(`[noctrace] Invalid container name: "${containerArg}"`);
+    process.exit(1);
+  }
+
+  // Verify container exists and is running
+  try {
+    assertContainerRunning(containerArg, defaultDockerRunner);
+  } catch (err) {
+    console.error(`[noctrace] ${err.message}`);
+    process.exit(1);
+  }
+
+  // Find Claude config dir inside the container
+  const claudeDir = resolveClaudeDir(containerArg, defaultDockerRunner);
+  console.log(`[noctrace] Connecting to container "${containerArg}" (claude dir: ${claudeDir})`);
+
+  // Check if curl or wget exists in the container
+  const httpTool = detectHttpTool(containerArg, defaultDockerRunner);
+  if (httpTool === 'none') {
+    console.error('[noctrace] Container has neither curl nor wget. Cannot stream sessions.');
+    console.error('[noctrace] Install curl in the container: apt-get install -y curl');
+    process.exit(1);
+  }
+
+  // Resolve host URL that the container can reach
+  const hostUrl = resolveHostUrl(containerArg, defaultDockerRunner);
+
+  // Start noctrace server on the host
+  process.env.NOCTRACE_NO_AUTOSTART = '1';
+  process.env.NODE_ENV = 'production';
+  const { startServer } = await import('../dist/server/server/index.js');
+  const openMod = await import('open');
+  const port = await startServer();
+  const url = `http://localhost:${port}`;
+  const containerTargetUrl = `${hostUrl}:${port}`;
+  console.log(`[noctrace] Dashboard: ${url}`);
+  console.log(`[noctrace] Container will stream to: ${containerTargetUrl}`);
+  await openMod.default(url);
+
+  // Read the watcher script from the package
+  const watcherScript = readFileSync(
+    new URL('./docker-watcher.sh', import.meta.url), 'utf8'
+  );
+
+  // Copy watcher script into the container
+  console.log(`[noctrace] Injecting watcher into container...`);
+  const tmpScript = path.join(os.tmpdir(), `noctrace-watcher-${Date.now()}.sh`);
+  writeFileSync(tmpScript, watcherScript);
+
+  try {
+    copyWatcherScript(containerArg, tmpScript, defaultDockerRunner);
+  } finally {
+    unlinkSync(tmpScript);
+  }
+
+  // Run the watcher in the background inside the container
+  spawnWatcher(containerArg, claudeDir, containerTargetUrl, defaultDockerRunner);
+
+  console.log(`[noctrace] Watcher injected. Streaming sessions in real-time.`);
+  console.log(`[noctrace] Press Ctrl+C to stop.`);
+
+  // Monitor heartbeats
+  let lastHeartbeatCheck = Date.now();
+  const heartbeatInterval = setInterval(async () => {
+    try {
+      const { default: http } = await import('node:http');
+      const result = await new Promise((resolve) => {
+        const req = http.get(`http://localhost:${port}/api/docker/status`, { timeout: 2000 }, (res) => {
+          let data = '';
+          res.on('data', (chunk) => { data += chunk; });
+          res.on('end', () => { try { resolve(JSON.parse(data)); } catch { resolve(null); } });
+        });
+        req.on('error', () => resolve(null));
+      });
+
+      if (result && result.containers) {
+        const container = result.containers.find((c) => c.name === containerArg);
+        if (container && container.stale && Date.now() - lastHeartbeatCheck > 30000) {
+          console.log(`[noctrace] Warning: No heartbeat from container "${containerArg}" in 30s. It may have stopped.`);
+          lastHeartbeatCheck = Date.now();
+        }
+      }
+    } catch { /* heartbeat check is best-effort */ }
+  }, 15000);
+
+  // Cleanup on exit
+  process.on('SIGINT', () => {
+    console.log('\n[noctrace] Stopping...');
+    clearInterval(heartbeatInterval);
+    cleanupWatcher(containerArg, defaultDockerRunner);
+    console.log('[noctrace] Stopped.');
+    process.exit(0);
+  });
+  process.on('SIGTERM', () => process.exit(0));
+
+  // Keep process alive
+  await new Promise(() => {});
+}
+
 if (args.includes('--mcp')) {
   // MCP mode: boot the Express server and speak JSON-RPC over stdio.
   // stdout is the JSON-RPC channel — all logging must go to stderr.