CLI-244 sonar callback — command infrastructure

Author: kirill-knize-sonarsource

CLAUDE.md

@@ -50,7 +50,7 @@ Please use the exception types defined in `src/cli/commands/_common/error.ts` fo
 
 ## Tests
 
-Please try to create integration tests in priority. If the test is too complicated to set up, write unit tests.
+Always prefer end-to-end integration tests. Unit tests are a last resort — only when e2e is genuinely impractical (e.g. the dependency cannot be controlled or isolated at all).
 Try to get inspiration from other tests to follow the same structure.
 
 - Unit tests: `tests/unit/` — run with `bun test:unit`

src/cli/command-tree.ts

@@ -229,6 +229,15 @@ COMMAND_TREE.command('self-update')
   .option('--force', 'Install the latest version even if already up to date')
   .anonymousAction((options: SelfUpdateOptions) => selfUpdate(options));
 
+// Hidden callback command — internal handlers for agent and git hooks.
+// Shell hook scripts call `sonar callback <event>` to delegate all business logic to TypeScript.
+export const callbackCommand = COMMAND_TREE.command('callback', { hidden: true })
+  .description('Internal callback handlers for agent and git hooks')
+  .enablePositionalOptions()
+  .anonymousAction(function (this: Command) {
+    this.outputHelp();
+  });
+
 // Hidden flush command — only registered when running as a telemetry worker.
 if (process.env[TELEMETRY_FLUSH_MODE_ENV]) {
   COMMAND_TREE.command('flush-telemetry', { hidden: true }).anonymousAction(flushTelemetry);

src/cli/commands/callback/stdin.ts

@@ -0,0 +1,55 @@
+/*
+ * SonarQube CLI
+ * Copyright (C) 2026 SonarSource Sàrl
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ */
+
+// Stdin reader used by all sonar callback handlers.
+// Hook agents pipe their JSON event payload to the callback process via stdin.
+
+const STDIN_TIMEOUT_MS = 5000;
+
+/**
+ * Read stdin, parse as JSON, and return the result typed as T.
+ * Throws if stdin is not valid JSON or if the read times out.
+ */
+export async function readStdinJson<T>(): Promise<T> {
+  const raw = await readRawStdin();
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    throw new Error('Failed to parse stdin as JSON');
+  }
+}
+
+async function readRawStdin(): Promise<string> {
+  return Promise.race([
+    new Promise<string>((resolve, reject) => {
+      const chunks: Buffer[] = [];
+      process.stdin.on('data', (chunk: Buffer) => chunks.push(chunk));
+      process.stdin.on('end', () => {
+        resolve(Buffer.concat(chunks).toString('utf-8'));
+      });
+      process.stdin.on('error', reject);
+    }),
+    new Promise<never>((_, reject) =>
+      setTimeout(() => {
+        reject(new Error(`stdin read timed out after ${STDIN_TIMEOUT_MS}ms`));
+      }, STDIN_TIMEOUT_MS),
+    ),
+  ]);
+}

tests/integration/specs/callback/callback.test.ts

@@ -0,0 +1,65 @@
+/*
+ * SonarQube CLI
+ * Copyright (C) 2026 SonarSource Sàrl
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ */
+
+// Integration tests for `sonar hook` command infrastructure
+
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { TestHarness } from '../../harness';
+
+describe('sonar hook', () => {
+  let harness: TestHarness;
+
+  beforeEach(async () => {
+    harness = await TestHarness.create();
+  });
+
+  afterEach(async () => {
+    await harness.dispose();
+  });
+
+  it(
+    'is hidden — does not appear in root help',
+    async () => {
+      const result = await harness.run('');
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).not.toContain('callback');
+    },
+    { timeout: 15000 },
+  );
+
+  it(
+    'sonar hook --help exits 0 and shows usage',
+    async () => {
+      const result = await harness.run('hook --help');
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toContain('hook');
+    },
+    { timeout: 15000 },
+  );
+
+  it(
+    'sonar hook exits 0 (shows help)',
+    async () => {
+      const result = await harness.run('hook');
+      expect(result.exitCode).toBe(0);
+    },
+    { timeout: 15000 },
+  );
+});