noctrace 1.0.0 → 1.1.0

package/README.md

@@ -143,6 +143,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 |
+| `--devcontainer <path>` | Resolve the running devcontainer for a local folder path and attach to it. Pass `.` for the current directory. Falls back to `--docker` if you pass a container name directly |
 | `--install-hooks` | Configure Claude Code to push real-time events to noctrace |
 | `--uninstall-hooks` | Remove noctrace hooks from Claude Code |
 

package/bin/noctrace.js

@@ -197,14 +197,11 @@ 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);
-  }
-
+/**
+ * Run Docker watcher mode with a known, already-validated container ID.
+ * Shared by --docker and --devcontainer.
+ */
+async function runDockerMode(containerArg) {
   const {
     isValidContainerName,
     assertContainerRunning,
@@ -320,6 +317,44 @@ if (args.includes('--docker')) {
   await new Promise(() => {});
 }
 
+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);
+  }
+  await runDockerMode(containerArg);
+}
+
+if (args.includes('--devcontainer')) {
+  const devcontainerArg = args[args.indexOf('--devcontainer') + 1];
+  if (!devcontainerArg || devcontainerArg.startsWith('--')) {
+    console.error('[noctrace] Usage: npx noctrace --devcontainer <path-or-container>');
+    console.error('[noctrace] Examples:');
+    console.error('[noctrace]   npx noctrace --devcontainer .');
+    console.error('[noctrace]   npx noctrace --devcontainer /Users/me/myproject');
+    console.error('[noctrace]   npx noctrace --devcontainer my-devcontainer-id');
+    process.exit(1);
+  }
+
+  const { resolveDevcontainerContainer, defaultDockerRunner } =
+    await import('../dist/server/server/docker.js');
+
+  let resolvedContainer;
+  try {
+    resolvedContainer = resolveDevcontainerContainer(devcontainerArg, defaultDockerRunner);
+  } catch (err) {
+    const lines = err.message.split('\n');
+    for (const line of lines) {
+      console.error(`[noctrace] ${line}`);
+    }
+    process.exit(1);
+  }
+
+  await runDockerMode(resolvedContainer);
+}
+
 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.

package/dist/server/server/docker.js

@@ -5,6 +5,8 @@
  * watcher injection, and cleanup.  All Docker commands go through the
  * DockerRunner interface so callers (and tests) can swap in a stub.
  */
+import path from 'node:path';
+import os from 'node:os';
 // ---------------------------------------------------------------------------
 // Default runner (real child_process)
 // ---------------------------------------------------------------------------
@@ -150,3 +152,66 @@ export function cleanupWatcher(containerArg, runner) {
     }
     catch { /* container may be gone */ }
 }
+// ---------------------------------------------------------------------------
+// Devcontainer support
+// ---------------------------------------------------------------------------
+/**
+ * Look up a running container by an exact Docker label match.
+ * Returns the container ID (short form), or null when nothing matches.
+ *
+ * Uses `docker ps --filter "label=<label>=<value>" --format "{{.ID}}"`.
+ * The label and value are passed as a single `label=key=value` filter argument
+ * so no shell interpolation occurs.
+ */
+export function findContainerByLabel(label, value, runner) {
+    let output;
+    try {
+        output = runner.execSync('docker', ['ps', '--filter', `label=${label}=${value}`, '--format', '{{.ID}}'], { stdio: 'pipe' });
+    }
+    catch {
+        return null;
+    }
+    const id = output.trim().split('\n')[0]?.trim() ?? '';
+    return id.length > 0 ? id : null;
+}
+/**
+ * Resolve a devcontainer argument to a concrete container ID.
+ *
+ * If `input` looks like a path (starts with `/`, `.`, `./`, or `~/`) it is
+ * resolved to an absolute path and looked up via the canonical
+ * `devcontainer.local_folder` label, falling back to the older
+ * `vsch.local.folder` label.  When neither label matches an error is thrown
+ * with a clear hint pointing the user at `docker ps --filter "label=devcontainer.*"`.
+ *
+ * If `input` is not a path it is treated as a container name/ID.
+ * `isValidContainerName` is checked and the value is returned directly.
+ *
+ * @param cwd - Working directory used to resolve relative paths. Defaults to `process.cwd()`.
+ */
+export function resolveDevcontainerContainer(input, runner, cwd) {
+    const isPath = input.startsWith('/') || input.startsWith('.') || input.startsWith('~/');
+    if (!isPath) {
+        if (!isValidContainerName(input)) {
+            throw new Error(`Invalid container name: "${input}"`);
+        }
+        return input;
+    }
+    // Resolve to an absolute path — devcontainer labels always store absolute paths.
+    // path.resolve does not expand ~ so handle that explicitly.
+    let absPath;
+    if (input.startsWith('~/')) {
+        absPath = path.join(os.homedir(), input.slice(2));
+    }
+    else {
+        absPath = path.resolve(cwd ?? process.cwd(), input);
+    }
+    // Try canonical label first, then the older VS Code label.
+    const id = findContainerByLabel('devcontainer.local_folder', absPath, runner) ??
+        findContainerByLabel('vsch.local.folder', absPath, runner);
+    if (id === null) {
+        throw new Error(`No devcontainer found for path: ${absPath}\n` +
+            `Hint: make sure the devcontainer is running, then check:\n` +
+            `  docker ps --filter "label=devcontainer.local_folder"`);
+    }
+    return id;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "noctrace",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Claude Code observability — DevTools-style waterfall visualizer for AI agent workflows, token tracking, and context health monitoring",
   "type": "module",
   "license": "MIT",