Gate terminal chunk debug logs

packages/component-sdk/src/__tests__/terminal-chunk.test.ts

@@ -50,13 +50,67 @@ describe('Terminal chunk emitter', () => {
     expect(timeDiff).toBeGreaterThanOrEqual(25);
   });
 
-    it('no-ops when terminalCollector is missing', () => {
+  it('does not write debug logs by default', () => {
+    const debugSpy = vi.spyOn(console, 'debug').mockImplementation(() => {});
+
+    try {
+      const collector = vi.fn();
+      const context = createExecutionContext({
+        runId: 'run-1',
+        componentRef: 'node.a',
+        terminalCollector: collector,
+      });
+
+      const emitter = createTerminalChunkEmitter(context, 'stdout');
+      emitter('data');
+
+      expect(debugSpy).not.toHaveBeenCalled();
+    } finally {
+      debugSpy.mockRestore();
+    }
+  });
+
+  it('writes debug logs when terminal debug logging is enabled', () => {
+    const previousDebugFlag = process.env.SENTRIS_DEBUG_TERMINAL;
+    const debugSpy = vi.spyOn(console, 'debug').mockImplementation(() => {});
+
+    try {
+      process.env.SENTRIS_DEBUG_TERMINAL = '1';
+      const collector = vi.fn();
       const context = createExecutionContext({
         runId: 'run-1',
         componentRef: 'node.a',
+        terminalCollector: collector,
       });
 
       const emitter = createTerminalChunkEmitter(context, 'stdout');
-      expect(() => emitter('data')).not.toThrow();
+      emitter('data');
+
+      expect(debugSpy).toHaveBeenCalledWith(
+        '[TerminalChunkEmitter] emitting chunk',
+        expect.objectContaining({
+          nodeRef: 'node.a',
+          chunkIndex: 1,
+          dataLength: 4,
+        }),
+      );
+    } finally {
+      if (previousDebugFlag === undefined) {
+        delete process.env.SENTRIS_DEBUG_TERMINAL;
+      } else {
+        process.env.SENTRIS_DEBUG_TERMINAL = previousDebugFlag;
+      }
+      debugSpy.mockRestore();
+    }
+  });
+
+  it('no-ops when terminalCollector is missing', () => {
+    const context = createExecutionContext({
+      runId: 'run-1',
+      componentRef: 'node.a',
     });
+
+    const emitter = createTerminalChunkEmitter(context, 'stdout');
+    expect(() => emitter('data')).not.toThrow();
+  });
 });

packages/component-sdk/src/terminal.ts

@@ -2,6 +2,10 @@ import type { TerminalChunkInput, ExecutionContext } from './types';
 
 export type TerminalChunkEmitter = (data: Uint8Array | string) => void;
 
+function shouldDebugTerminalChunks(): boolean {
+  return process.env.SENTRIS_DEBUG_TERMINAL === '1';
+}
+
 export function createTerminalChunkEmitter(
   context: ExecutionContext,
   stream: TerminalChunkInput['stream'] = 'pty',
@@ -45,7 +49,10 @@ export function createTerminalChunkEmitter(
       runnerKind: 'docker',
     };
 
-    if (chunkIndex <= 3 || dataString.includes('[') || dataString.includes('progress')) {
+    if (
+      shouldDebugTerminalChunks() &&
+      (chunkIndex <= 3 || dataString.includes('[') || dataString.includes('progress'))
+    ) {
       console.debug('[TerminalChunkEmitter] emitting chunk', {
         nodeRef: context.componentRef,
         stream,