PR feedback: rename symbols, remove codex stub, fix hook naming, update tests

- Rename scanFiles → scanFilesForSecrets in secrets-scan.ts
- Rename callbackCommand → hookCommand in command-tree.ts
- Remove codex-pre-tool-use command (out of scope)
- Remove PR-specific comments from command-tree.ts
- Rename agent-prompt-submit → claude-prompt-submit
- Rename agent-post-tool-use → claude-post-tool-use
- Consolidate duplicate hook.test.ts tests, assert description shown
- Update README.md via gen:docs

Author: kirill-knize-sonarsource

README.md

@@ -154,6 +154,7 @@ Revoke a user token
 sonar api post "/api/user_tokens/revoke" --data '{"name":"my-token"}'
 ```
 
+
 ---
 
 ### `sonar integrate`
@@ -180,7 +181,7 @@ Setup SonarQube integration for Claude Code. This will install secrets scanning
 
 | Option              | Type    | Required | Description                                                                 | Default |
 | ------------------- | ------- | -------- | --------------------------------------------------------------------------- | ------- |
-| `--project`, `-p`   | string  | No       | Project key                                                                 | -       |
+| `--project`, `-p`   | string  | No       | SonarCloud project key (overrides auto-detected project)                    | -       |
 | `--non-interactive` | boolean | No       | Non-interactive mode (no prompts)                                           | -       |
 | `--global`, `-g`    | boolean | No       | Install hooks and config globally to ~/.claude instead of project directory | -       |
 
@@ -391,6 +392,40 @@ Update sonar CLI to the latest version
 
 ---
 
+### `sonar hook`
+
+Internal callback handlers for agent and git hooks
+
+#### `sonar hook claude-pre-tool-use`
+
+PreToolUse handler: scan files for secrets before agent reads them
+
+---
+
+#### `sonar hook codex-pre-tool-use`
+
+PreToolUse handler for Codex: scan files for secrets before agent reads them
+
+---
+
+#### `sonar hook agent-prompt-submit`
+
+UserPromptSubmit handler: scan prompts for secrets before sending
+
+---
+
+#### `sonar hook agent-post-tool-use`
+
+PostToolUse handler: run SQAA analysis on modified files
+
+**Options:**
+
+| Option            | Type   | Required | Description            | Default |
+| ----------------- | ------ | -------- | ---------------------- | ------- |
+| `--project`, `-p` | string | No       | SonarCloud project key | -       |
+
+---
+
 ## Option Types
 
 - `string` — text value (e.g. `--server https://sonarcloud.io`)
@@ -425,7 +460,7 @@ Both are enabled by default and share the same opt-out toggle. To disable all da
 sonar config telemetry --disabled
 ```
 
-No personally identifiable information is transmitted. File paths in error reports are anonymized by replacing your home directory with `~`.
+No personally identifiable information is transmitted.
 
 ## Contributing
 

src/cli/command-tree.ts

@@ -232,36 +232,27 @@ COMMAND_TREE.command('self-update')
 
 // Hidden callback command — internal handlers for agent and git hooks.
 // Shell hook scripts call `sonar hook <event>` to delegate all business logic to TypeScript.
-export const callbackCommand = COMMAND_TREE.command('hook', { hidden: true })
-  .description('Internal callback handlers for agent and git hooks')
+export const hookCommand = COMMAND_TREE.command('hook', { hidden: true })
+  .description('Internal hook handlers for agent and git hooks')
   .enablePositionalOptions()
   .anonymousAction(function (this: Command) {
     this.outputHelp();
   });
 
-callbackCommand
+hookCommand
   .command('claude-pre-tool-use')
   .description('PreToolUse handler: scan files for secrets before agent reads them')
   .anonymousAction(() => claudePreToolUse());
 
-// codex-pre-tool-use reuses the same handler (same hook event, different agent name)
-callbackCommand
-  .command('codex-pre-tool-use')
-  .description('PreToolUse handler for Codex: scan files for secrets before agent reads them')
-  .anonymousAction(() => claudePreToolUse());
-
-// agent-prompt-submit and agent-post-tool-use are installed by `sonar integrate claude`.
-// They are implemented in subsequent PRs; stubs here ensure scripts don't fail with
-// "unknown command" on a CLI that only has CLI-244/245.
-callbackCommand
-  .command('agent-prompt-submit')
+hookCommand
+  .command('claude-prompt-submit')
   .description('UserPromptSubmit handler: scan prompts for secrets before sending')
   .anonymousAction(() => {
     return;
   });
 
-callbackCommand
-  .command('agent-post-tool-use')
+hookCommand
+  .command('claude-post-tool-use')
   .option('-p, --project <project>', 'SonarCloud project key')
   .description('PostToolUse handler: run SQAA analysis on modified files')
   .anonymousAction(() => {

src/cli/commands/_common/install/secrets.ts

@@ -217,3 +217,13 @@ function cleanupOldVersionBinaries(binDir: string, currentBinaryName: string): v
 export function buildLocalBinaryName(platformInfo: PlatformInfo): string {
   return `sonar-secrets-${SONAR_SECRETS_VERSION}${buildPlatformSuffix(platformInfo)}`;
 }
+
+/**
+ * Returns the path to the installed sonar-secrets binary, or null if not present.
+ * Never downloads — use this where silent operation is required (e.g. hook handlers).
+ */
+export function resolveSecretsBinaryPath(): string | null {
+  const platform = detectPlatform();
+  const binaryPath = join(BIN_DIR, buildLocalBinaryName(platform));
+  return existsSync(binaryPath) ? binaryPath : null;
+}

src/cli/commands/analyze/secrets.ts

@@ -18,8 +18,9 @@
  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  */
 import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import { spawnProcess } from '../../../lib/process';
-import type { SpawnResult } from '../../../lib/process';
+import type { SpawnOptions, SpawnResult } from '../../../lib/process';
 import type { ResolvedAuth } from '../../../lib/auth-resolver';
 import logger from '../../../lib/logger';
 import { blank, error, print, success, text } from '../../../ui';
@@ -45,32 +46,71 @@ const BINARY_AUTH_TOKEN_ENV = 'SONAR_SECRETS_TOKEN';
 const SCAN_TIMEOUT_MS = 30000;
 const STDIN_READ_TIMEOUT_MS = 5000;
 
+export const EXIT_CODE_SECRETS_FOUND = 51;
+
+/**
+ * Run sonar-secrets binary on the given files. Returns the full spawn result.
+ * Kills the child process on timeout.
+ */
+export async function runSecretsBinary(
+  binaryPath: string,
+  files: string[],
+  auth: ResolvedAuth,
+): Promise<SpawnResult> {
+  return spawnWithTimeout(binaryPath, ['--non-interactive', ...files], {
+    stdin: 'pipe',
+    stdout: 'pipe',
+    stderr: 'pipe',
+    env: buildAuthEnv(auth),
+  });
+}
+
+function buildAuthEnv(auth: ResolvedAuth): Record<string, string> {
+  return { [BINARY_AUTH_URL_ENV]: auth.serverUrl, [BINARY_AUTH_TOKEN_ENV]: auth.token };
+}
+
+async function spawnWithTimeout(
+  binaryPath: string,
+  args: string[],
+  options: SpawnOptions,
+): Promise<SpawnResult> {
+  let killChild: (() => void) | undefined;
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      spawnProcess(binaryPath, args, {
+        ...options,
+        onSpawn: (kill) => {
+          killChild = kill;
+        },
+      }),
+      new Promise<never>((_, reject) => {
+        timeoutId = setTimeout(() => {
+          killChild?.();
+          reject(new Error(`Scan timed out after ${SCAN_TIMEOUT_MS}ms`));
+        }, SCAN_TIMEOUT_MS);
+      }),
+    ]);
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
 async function handleCheckCommand(
   options: AnalyzeSecretsOptions,
   auth: ResolvedAuth,
 ): Promise<void> {
   validateScanOptions(options);
   const binaryPath = await installSecretsBinary();
-  const { authUrl, authToken } = setupScanEnvironment(binaryPath, auth);
   const scanStartTime = Date.now();
 
   if (options.stdin) {
-    await performStdinScan(binaryPath, authUrl, authToken, scanStartTime);
+    reportScanResult(await runScanFromStdin(binaryPath, auth), scanStartTime);
   } else {
-    await performPathsScan(binaryPath, options.paths ?? [], authUrl, authToken, scanStartTime);
+    await performPathsScan(binaryPath, options.paths ?? [], auth, scanStartTime);
   }
 }
 
-interface ScanEnvironment {
-  binaryPath: string;
-  authUrl?: string;
-  authToken?: string;
-}
-
-function setupScanEnvironment(binaryPath: string, auth: ResolvedAuth): ScanEnvironment {
-  return { binaryPath, authUrl: auth.serverUrl, authToken: auth.token };
-}
-
 function validateScanOptions(options: { paths?: string[]; stdin?: boolean }): void {
   const hasPaths = (options.paths?.length ?? 0) > 0;
   if (!hasPaths && !options.stdin) {
@@ -82,28 +122,10 @@ function validateScanOptions(options: { paths?: string[]; stdin?: boolean }): vo
   }
 }
 
-async function performStdinScan(
-  binaryPath: string,
-  authUrl: string | undefined,
-  authToken: string | undefined,
-  scanStartTime: number,
-): Promise<void> {
-  const result = await runScanFromStdin(binaryPath, authUrl, authToken);
-  const scanDurationMs = Date.now() - scanStartTime;
-
-  const exitCode = result.exitCode ?? 1;
-  if (exitCode === 0) {
-    handleScanSuccess(result, scanDurationMs);
-  } else {
-    handleScanFailure(result, scanDurationMs, exitCode);
-  }
-}
-
 async function performPathsScan(
   binaryPath: string,
   paths: string[],
-  authUrl: string | undefined,
-  authToken: string | undefined,
+  auth: ResolvedAuth,
   scanStartTime: number,
 ): Promise<void> {
   if (paths.length === 0) {
@@ -116,9 +138,12 @@ async function performPathsScan(
     }
   }
 
-  const result = await runScan(binaryPath, paths, authUrl, authToken);
-  const scanDurationMs = Date.now() - scanStartTime;
+  const result = await runSecretsBinary(binaryPath, paths, auth);
+  reportScanResult(result, scanStartTime);
+}
 
+function reportScanResult(result: SpawnResult, scanStartTime: number): void {
+  const scanDurationMs = Date.now() - scanStartTime;
   const exitCode = result.exitCode ?? 1;
   if (exitCode === 0) {
     handleScanSuccess(result, scanDurationMs);
@@ -127,72 +152,21 @@ async function performPathsScan(
   }
 }
 
-async function runScan(
-  binaryPath: string,
-  paths: string[],
-  authUrl: string | undefined,
-  authToken: string | undefined,
-): Promise<SpawnResult> {
-  let timeoutId: ReturnType<typeof setTimeout> | undefined;
-  try {
-    return await Promise.race([
-      spawnProcess(binaryPath, ['--non-interactive', ...paths], {
-        stdin: 'pipe',
-        stdout: 'pipe',
-        stderr: 'pipe',
-        env: {
-          ...(authUrl && authToken
-            ? { [BINARY_AUTH_URL_ENV]: authUrl, [BINARY_AUTH_TOKEN_ENV]: authToken }
-            : {}),
-        },
-      }),
-      new Promise<never>((_resolve, reject) => {
-        timeoutId = setTimeout(() => {
-          reject(new Error(`Scan timed out after ${SCAN_TIMEOUT_MS}ms`));
-        }, SCAN_TIMEOUT_MS);
-      }),
-    ]);
-  } finally {
-    clearTimeout(timeoutId);
-  }
-}
-
-async function runScanFromStdin(
-  binaryPath: string,
-  authUrl: string | undefined,
-  authToken: string | undefined,
-): Promise<SpawnResult> {
+async function runScanFromStdin(binaryPath: string, auth: ResolvedAuth): Promise<SpawnResult> {
   const { writeFileSync, unlinkSync } = await import('node:fs');
   const { tmpdir } = await import('node:os');
-  const pathModule = await import('node:path');
-  const pathJoin = (...args: string[]) => pathModule.join(...args);
 
   const stdinData = await readStdin();
+  const tempFile = join(tmpdir(), `sonar-secrets-scan-${Date.now()}.tmp`);
 
-  const tempFile = pathJoin(tmpdir(), `sonar-secrets-scan-${Date.now()}.tmp`);
-
-  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+  writeFileSync(tempFile, stdinData);
   try {
-    writeFileSync(tempFile, stdinData);
-
-    return await Promise.race([
-      spawnProcess(binaryPath, [tempFile], {
-        stdout: 'pipe',
-        stderr: 'pipe',
-        env: {
-          ...(authUrl && authToken
-            ? { [BINARY_AUTH_URL_ENV]: authUrl, [BINARY_AUTH_TOKEN_ENV]: authToken }
-            : {}),
-        },
-      }),
-      new Promise<never>((_resolve, reject) => {
-        timeoutId = setTimeout(() => {
-          reject(new Error(`Scan timed out after ${SCAN_TIMEOUT_MS}ms`));
-        }, SCAN_TIMEOUT_MS);
-      }),
-    ]);
+    return await spawnWithTimeout(binaryPath, [tempFile], {
+      stdout: 'pipe',
+      stderr: 'pipe',
+      env: buildAuthEnv(auth),
+    });
   } finally {
-    clearTimeout(timeoutId);
     try {
       unlinkSync(tempFile);
     } catch {
@@ -228,21 +202,18 @@ async function readStdin(): Promise<string> {
 }
 
 function handleScanSuccess(result: { stdout: string }, scanDurationMs: number): void {
+  blank();
+  success('Scan completed successfully');
   try {
     const scanResult = JSON.parse(result.stdout);
-    blank();
-    success('Scan completed successfully');
     text(`  Duration: ${scanDurationMs}ms`);
     displayScanResults(scanResult);
-    blank();
   } catch (parseError) {
     logger.debug(`Failed to parse JSON output: ${(parseError as Error).message}`);
     blank();
-    success('Scan completed successfully');
-    blank();
     print(result.stdout);
-    blank();
   }
+  blank();
 }
 
 function displayScanResults(scanResult: {
@@ -270,8 +241,6 @@ function displayScanResults(scanResult: {
   });
 }
 
-const EXIT_CODE_SECRETS_FOUND = 51;
-
 function handleScanFailure(
   result: { exitCode: number | null; stderr: string; stdout: string },
   scanDurationMs: number,
@@ -293,11 +262,7 @@ function handleScanFailure(
 }
 
 function handleScanError(err: unknown): void {
-  if (err instanceof InvalidOptionError) {
-    throw err;
-  }
-
-  if (err instanceof CommandFailedError) {
+  if (err instanceof InvalidOptionError || err instanceof CommandFailedError) {
     throw err;
   }