codeant-cli 0.5.8 → 0.5.10

package/findings.md

@@ -49,9 +49,9 @@ codeant findings repo \
   --output codeant.sarif
 ```
 
-Supported repo types are `sast`, `sca`, `secrets`, `iac`, `dead_code`, `sbom`, `anti_patterns`, `docstring`, and `complex_functions`. Use `--types all` for all of them. Formats are `json`, `sarif`, `csv`, `md`, and `table`; JSON is the default.
+Supported repo types are `sast`, `sca`, `secrets`, `iac`, `dead_code`, `duplicate_code`, `sbom`, `anti_patterns`, `docstring`, and `complex_functions`. Use `--types all` for all of them. Formats are `json`, `sarif`, `csv`, `md`, and `table`; JSON is the default.
 
-Use `--filter-dismissed` to exclude dismissed findings and `--no-false-positives` to exclude false positives. `--path`, `--check`, `--limit`, and `--offset` support agent-friendly filtering and pagination.
+Use `--filter-dismissed` to exclude dismissed findings and `--no-false-positives` to exclude false positives, including ones users marked in the app. Without those flags, such findings are returned with `metadata.dismissed` or `metadata.false_positive`. `--path`, `--check`, `--limit`, and `--offset` support agent-friendly filtering and pagination.
 
 ## Organization Hotlist findings
 

package/mcp.md

@@ -11,18 +11,19 @@ The CodeAnt CLI ships an MCP (Model Context Protocol) server that exposes CodeAn
 | Name | Read/Write | What it does |
 |------|------------|--------------|
 | `codeant_scans_orgs` | read | List authenticated CodeAnt orgs. |
-| `codeant_scans_repos` | read | List repos in an org. |
+| `codeant_scans_repos` | read | List repos in an org (slim records, paged: `search`, `limit`, `offset`, `full`). |
 | `codeant_scans_history` | read | Recent scan runs for a repo. |
 | `codeant_scans_get` | read | Severity/category summary for one scan. |
 | `codeant_scans_results` | read | Full findings (SAST, SCA, secrets, IaC, …) for one scan. |
-| `codeant_scans_dismissed` | read | Dismissed alerts for a repo. |
+| `codeant_scans_dismissed` | read | Dismissed alerts for a repo (any analysis type; `sast` and `anti_patterns` are accepted as aliases). |
+| `codeant_scans_overrides` | read | User false-positive, confidence, and severity overrides for a repo. |
 | `codeant_hotlist_list` | read | Prioritized organization-wide Hotlist findings with stable IDs. |
 | `codeant_hotlist_get` | read | One complete Hotlist finding by stable ID. |
 | `codeant_findings_antipatterns` | read | Anti-pattern findings across selected or all organization repos (paged: `limit`, `offset`, `all`). |
-| `codeant_cloud_scan_history` | read | AWS/Azure/GCP CSPM, VM, or container scan history. |
-| `codeant_cloud_findings_list` | read | Findings for one CSPM, VM, or container scan (VM/container paged: `limit`, `offset`, `all`). |
+| `codeant_cloud_scan_history` | read | AWS/Azure/GCP CSPM, VM, or container scan history (newest first, 10 per provider by default and up to 200, paged with `limit`/`offset`, without per-service rollups unless `full`). |
+| `codeant_cloud_findings_list` | read | Findings for one CSPM, VM, or container scan (paged: `limit`, `offset`, `all`; compliance mappings only with `full`). |
 | `codeant_cloud_finding_get` | read | Full detail for one cloud finding UID. |
-| `codeant_pentest_history` | read | Pentest engagement history. |
+| `codeant_pentest_history` | read | Pentest engagement history (paged: `limit`, `offset`, `full`). |
 | `codeant_pentest_issues` | read | All available issues for a pentest engagement. |
 | `codeant_pentest_report` | read | Full pentest customer report. |
 | `codeant_api_get` | read | Authenticated GET request to any relative CodeAnt app API path, with exact org/provider context. |
@@ -30,7 +31,9 @@ The CodeAnt CLI ships an MCP (Model Context Protocol) server that exposes CodeAn
 | `codeant_pr_get` | read | Detail for a PR/MR. |
 | `codeant_pr_comments` | read | Comments on a PR, filtered. |
 | `codeant_comments_search` | read | Free-text search across CodeAnt review comments. |
-| `codeant_review_local` | read | Run a CodeAnt review on local working-copy changes. |
+| `codeant_review_local` | read | Run a CodeAnt review on local working-copy changes in the server's working directory. |
+| `codeant_login` | auth | Start browser sign-in; returns the sign-in link immediately. Call again to confirm. |
+| `codeant_logout` | auth | Revoke and clear the saved token (shared with the CLI). |
 | `codeant_scans_start` | **write** | Trigger a new scan. Gated. |
 | `codeant_pr_resolve` | **write** | Resolve a PR conversation thread. Gated. |
 | `codeant_api_request` | **write** | Authenticated POST/PUT/PATCH/DELETE request to a relative CodeAnt app API path, with exact org/provider context. Gated. |
@@ -39,17 +42,24 @@ Write tools are only registered when `CODEANT_READ_ONLY=0`. Default = read-only.
 
 For complete finding coverage, examples, tenant/provider selection, and response details, see the [CodeAnt findings documentation](https://docs.codeant.ai/cli/findings).
 
-Every tool carries MCP annotations (`title`, `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) so the client can decide whether to auto-approve calls.
+Every tool carries MCP annotations (`title`, `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) so the client can decide whether to auto-approve calls. The server also sends `instructions` (discovery order, paging, auth recovery) in its `initialize` result.
+
+Results are compact JSON. Any result over `CODEANT_MCP_MAX_RESULT_CHARS` characters is refused with an error and a narrowing hint; [src/mcp/shape.js](src/mcp/shape.js) holds the MCP-only projections and page defaults. CLI commands keep their full output.
+
+`codeant_login` runs sign-in in the background: the first call returns `{ status: "pending", loginUrl, browserOpened }`, and the next call returns `{ status: "success" }` once the user finishes. The token is read from `~/.codeant/config.json` on every request, so CLI logins and logouts apply to a running server.
 
 ## Configuration (env vars)
 
 | Var | Purpose | Default |
 |-----|---------|---------|
-| `CODEANT_API_TOKEN` | API token (CodeAnt account → settings → API). Required. | — |
-| `CODEANT_API_URL` | API base URL. Override for self-hosted. | `https://api.codeant.ai` |
-| `CODEANT_READ_ONLY` | `1` to hide write tools, `0` to expose them. | `1` |
+| `CODEANT_API_TOKEN` | API token. Optional: without it the server uses the token saved by `codeant login` or `codeant_login`. | — |
+| `CODEANT_API_URL` | API base URL. Override for self-hosted. | `https://service.codeant.ai` |
+| `CODEANT_DASHBOARD_URL` | Web app URL used by `codeant_login`. Needed on self-hosted base URLs. | detected |
+| `CODEANT_READ_ONLY` | `0` or `false` exposes write tools; anything else hides them. | read-only |
+| `CODEANT_TELEMETRY_DISABLED` | `1` or `true` stops usage events (PostHog, tied to the API token). | enabled |
+| `CODEANT_MCP_MAX_RESULT_CHARS` | Largest tool result, in characters, before the server refuses it with a hint. | `80000` |
 
-The CLI also reads these from `~/.codeant/config.json` when not set in env. For MCP usage prefer env — it keeps per-client config explicit.
+The token, base URL, and dashboard URL fall back to `~/.codeant/config.json` when not set in env. PR tools also need an SCM token (`GITHUB_TOKEN`, `GITLAB_TOKEN`, `BITBUCKET_TOKEN`, `AZURE_DEVOPS_TOKEN`) and, for Azure DevOps, `AZURE_DEVOPS_ORG_URL`.
 
 ---
 
@@ -108,10 +118,13 @@ npm run mcpb:build
 open -a Claude dist/codeant.mcpb
 ```
 
-Claude pops an install dialog asking for the `user_config` fields:
-- **CodeAnt API token** (sensitive, required)
-- **API base URL** (defaults to `https://api.codeant.ai`)
+Claude pops an install dialog asking for the `user_config` fields (all optional):
+- **CodeAnt API token** (sensitive; leave blank and call `codeant_login` instead)
+- **API base URL** (defaults to `https://api.codeant.ai`, which the CLI maps to `https://service.codeant.ai`)
+- **Dashboard URL** (self-hosted only; used by `codeant_login`)
 - **Read-only mode** (defaults to on)
+- **Disable telemetry** (defaults to off)
+- SCM tokens and self-hosted SCM URLs for the PR tools
 
 After install, manage it in **Settings → Connectors**.
 
@@ -161,7 +174,7 @@ cd dist/mcpb-stage
   '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'; sleep 1) | node server/index.js
 ```
 
-Expect 23 tools in the `tools/list` response (or 26 if `CODEANT_READ_ONLY=0`).
+Expect 24 tools in the `tools/list` response (or 27 if `CODEANT_READ_ONLY=0`). `tests/mcp/server.test.js` checks that this list matches the manifest's `tools`.
 
 ### Bumping the version
 
@@ -190,9 +203,9 @@ CodeAnt's MCP server uses stdio + a packaged bundle, so the submission route is
 
 Reviewer notes worth preparing:
 
-- **Auth model.** CodeAnt uses a user-scoped API token entered into `user_config.api_token`. The token never leaves the user's machine — the bundle talks to `api.codeant.ai` (or the user's self-hosted URL) directly. No third-party OAuth flow needed.
+- **Auth model.** Users sign in with the `codeant_login` tool (browser sign-in, token saved to `~/.codeant/config.json`) or paste a token into `user_config.api_token`. The token is stored only on the user's machine (`~/.codeant/config.json`) and is sent only to the CodeAnt API (or the user's self-hosted URL) as a Bearer token — never to any third party. No third-party OAuth flow needed.
 - **Sandbox creds.** Email support@codeant.ai for a reviewer sandbox token; paste it into the submission form's reviewer-notes field along with an org slug that has scans + PRs to browse.
-- **Write tools.** Gated behind `user_config.read_only` (defaults to on). Reviewers can toggle off to test `codeant_scans_start` / `codeant_pr_resolve`.
+- **Write tools.** Gated behind `user_config.read_only` (defaults to on). Reviewers can toggle off to test `codeant_scans_start` / `codeant_pr_resolve` / `codeant_api_request`.
 
 ---
 
@@ -203,5 +216,8 @@ Reviewer notes worth preparing:
 | Server fails to start in Claude Desktop | `~/Library/Logs/Claude/mcp-server-codeant.log` |
 | Tool calls return errors | Same log — server stderr is captured there. |
 | Tool not listed at all | Check `CODEANT_READ_ONLY` — write tools are hidden when set to `1`. |
-| Auth errors on every tool | Confirm `CODEANT_API_TOKEN` is set in the MCP env (not just in `~/.codeant/config.json`). |
+| Auth errors on every tool | Call `codeant_login`, or run `codeant login` in a terminal; the server reads `~/.codeant/config.json` on every request. An explicit `CODEANT_API_TOKEN` in the MCP env takes precedence, so check it is current. |
+| `codeant_login` fails on a self-hosted instance | Set `CODEANT_DASHBOARD_URL` (or the MCPB **Dashboard URL** setting, or `codeant set-dashboard-url`). |
+| A tool returns "Result too large" | Follow the hint (smaller `limit`, filters, `fields`), or raise `CODEANT_MCP_MAX_RESULT_CHARS` if your client accepts larger results. |
+| `codeant_review_local` returns "Could not find a .git directory" | The client started the server outside a git repository (Claude Desktop does). Use a project-scoped client such as Claude Code. |
 | MCPB install dialog never appears | Open `.mcpb` with `open -a Claude dist/codeant.mcpb` to force the desktop app to handle it. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeant-cli",
-  "version": "0.5.8",
+  "version": "0.5.10",
   "description": "Code review CLI tool",
   "type": "module",
   "repository": {
@@ -36,6 +36,7 @@
     "./scans/fetch-results": "./src/scans/fetchScanResults.js",
     "./scans/fetch-advanced-results": "./src/scans/fetchAdvancedScanResults.js",
     "./scans/dismissed-alerts": "./src/scans/fetchDismissedAlerts.js",
+    "./scans/issue-overrides": "./src/scans/fetchIssueOverrides.js",
     "./hotlist": "./src/hotlist/client.js",
     "./findings/cloud": "./src/findings/cloud.js",
     "./findings/pentest": "./src/findings/pentest.js",

package/scans.md

@@ -135,11 +135,12 @@ codeant scans results --repo <owner/repo> [options]
 | `--repo <repo>` | **(required)** Repository in `owner/repo` format |
 | `--scan <sha>` | Specific commit SHA to use |
 | `--branch <name>` | Resolve latest scan on this branch |
-| `--types <list>` | Comma-separated types: `sast`, `sca`, `secrets`, `iac`, `dead_code`, `sbom`, `anti_patterns`, `docstring`, `complex_functions`, `all` (default: `all`) |
+| `--types <list>` | Comma-separated types: `sast`, `sca`, `secrets`, `iac`, `dead_code`, `duplicate_code`, `sbom`, `anti_patterns`, `docstring`, `complex_functions`, `all` (default: `all`) |
 | `--severity <list>` | Filter by severity (e.g. `critical,high`) |
 | `--path <glob>` | Filter by file path glob |
 | `--check <regex>` | Filter by check ID or name (regex) |
-| `--include-dismissed` | Include dismissed findings (excluded by default) |
+| `--filter-dismissed` | Exclude dismissed findings (included by default, marked `metadata.dismissed`) |
+| `--no-false-positives` | Exclude false positives, including ones users marked in the app (included by default, marked `metadata.false_positive`) |
 | `--format <fmt>` | Output format: `json`, `sarif`, `csv`, `md`, `table` (default: `json`) |
 | `--output <path>` | Write output to file instead of stdout |
 | `--fields <list>` | Project findings to a subset of fields (comma-separated) |
@@ -173,8 +174,8 @@ codeant scans results --repo acme/backend --format md
 # Output as SARIF to a file
 codeant scans results --repo acme/backend --format sarif --output results.sarif
 
-# Include dismissed findings
-codeant scans results --repo acme/backend --include-dismissed
+# Only open findings: drop dismissed findings and false positives
+codeant scans results --repo acme/backend --filter-dismissed --no-false-positives
 
 # Paginate through results
 codeant scans results --repo acme/backend --limit 50 --offset 100
@@ -206,7 +207,7 @@ codeant scans dismissed --repo <owner/repo> [options]
 | Option | Description |
 |--------|-------------|
 | `--repo <repo>` | **(required)** Repository in `owner/repo` format |
-| `--analysis-type <type>` | Analysis type: `security` or `secrets` (default: `security`) |
+| `--analysis-type <type>` | `security`, `secrets`, `sca`, `iac`, `antipatterns`, `docstring`, `complex_functions`, `dead_code`, or `duplicate_code` (default: `security`). Result-type names `sast` and `anti_patterns` are accepted too. |
 
 **Examples:**
 
@@ -220,6 +221,16 @@ codeant scans dismissed --repo acme/backend --analysis-type secrets
 
 ---
 
+### `scans overrides`
+
+List the per-finding overrides users set in the CodeAnt app: Mark/Unmark false positive (`security`, `iac`), secrets confidence (`secrets`), and Change Severity (`security`, `sca`). `scans results` already applies them.
+
+```bash
+codeant scans overrides --repo <owner/repo> [--analysis-type security|secrets|iac|sca]
+```
+
+---
+
 ### `scans start-scan`
 
 Trigger a new analysis run for a repository.

package/src/commands/scans/dismissed.js

@@ -1,16 +1,34 @@
 import { fetchDismissedAlerts } from '../../scans/fetchDismissedAlerts.js';
+import { fetchIssueOverrides } from '../../scans/fetchIssueOverrides.js';
 
-/**
- * codeant scans dismissed --repo <repo> [--analysis-type security|secrets]
- */
-export async function runDismissed({ repo, analysisType = 'security' } = {}) {
+// Result-type names (`scans results --types`) → the names dismissals and
+// overrides are stored under.
+const STORE_ANALYSIS_TYPES = {
+  sast: 'security',
+  security_issues: 'security',
+  anti_patterns: 'antipatterns',
+};
+
+export function storeAnalysisType(analysisType) {
+  return STORE_ANALYSIS_TYPES[analysisType] || analysisType;
+}
+
+function requireRepo(repo) {
   if (!repo) {
     const err = new Error('--repo is required');
     err.exitCode = 1;
     throw err;
   }
+}
+
+/**
+ * codeant scans dismissed --repo <repo> [--analysis-type <type>]
+ */
+export async function runDismissed({ repo, analysisType = 'security' } = {}) {
+  requireRepo(repo);
+  const type = storeAnalysisType(analysisType);
 
-  const result = await fetchDismissedAlerts(repo, analysisType);
+  const result = await fetchDismissedAlerts(repo, type);
   if (!result.success) {
     const err = new Error(result.error || 'Failed to fetch dismissed alerts');
     err.exitCode = 1;
@@ -19,8 +37,30 @@ export async function runDismissed({ repo, analysisType = 'security' } = {}) {
 
   return {
     repo,
-    analysis_type: analysisType,
+    analysis_type: type,
     total: result.dismissedAlerts.length,
     dismissed_alerts: result.dismissedAlerts,
   };
 }
+
+/**
+ * codeant scans overrides --repo <repo> [--analysis-type security|secrets|iac|sca]
+ */
+export async function runOverrides({ repo, analysisType = 'security' } = {}) {
+  requireRepo(repo);
+  const type = storeAnalysisType(analysisType);
+
+  const result = await fetchIssueOverrides(repo, type);
+  if (!result.success) {
+    const err = new Error(result.error || 'Failed to fetch issue overrides');
+    err.exitCode = 1;
+    throw err;
+  }
+
+  return {
+    repo,
+    analysis_type: type,
+    total: Object.keys(result.overrides).length,
+    overrides: result.overrides,
+  };
+}

package/src/commands/scans/index.js

@@ -3,10 +3,14 @@ import { runRepos } from './repos.js';
 import { runHistory } from './history.js';
 import { runGet } from './get.js';
 import { runResults } from './results.js';
-import { runDismissed } from './dismissed.js';
+import { runDismissed, runOverrides } from './dismissed.js';
 import { runStartScan } from './start-scan.js';
 import { setQuiet, setNoColor } from './lib/log.js';
 import { setNoColor as tableSetNoColor } from './formatters/table.js';
+import { intOption } from '../../utils/intOption.js';
+
+const toCount = intOption({ min: 1 });
+const toOffset = intOption();
 
 /**
  * Register all `codeant scans <verb>` subcommands.
@@ -37,7 +41,7 @@ export default function registerScansCommands(program, { runCmd }) {
     .requiredOption('--repo <repo>', 'Repository (owner/repo)')
     .option('--branch <name>', 'Filter by branch name')
     .option('--since <iso>', 'Show scans since ISO date')
-    .option('--limit <n>', 'Max results (default: 20)', parseInt, 20)
+    .option('--limit <n>', 'Max results (default: 20)', toCount, 20)
     .action((opts) =>
       runCmd(() => runHistory({ repo: opts.repo, branch: opts.branch, since: opts.since, limit: opts.limit }))
     );
@@ -65,7 +69,7 @@ export default function registerScansCommands(program, { runCmd }) {
     .option('--branch <name>', 'Resolve latest scan on this branch')
     .option(
       '--types <list>',
-      'Comma-separated types: sast,sca,secrets,iac,dead_code,sbom,anti_patterns,docstring,complex_functions,all',
+      'Comma-separated types: sast,sca,secrets,iac,dead_code,duplicate_code,sbom,anti_patterns,docstring,complex_functions,all',
       'all'
     )
     .option('--severity <list>', 'Filter by severity (e.g. critical,high)')
@@ -76,8 +80,8 @@ export default function registerScansCommands(program, { runCmd }) {
     .option('--format <fmt>', 'Output format: json|sarif|csv|md|table (default: json)', 'json')
     .option('--output <path>', 'Write output to file instead of stdout')
     .option('--fields <list>', 'Project findings to subset of fields (comma-separated)')
-    .option('--limit <n>', 'Max findings per page (default: 100)', parseInt, 100)
-    .option('--offset <n>', 'Pagination offset (default: 0)', parseInt, 0)
+    .option('--limit <n>', 'Max findings per page (default: 100)', toCount, 100)
+    .option('--offset <n>', 'Pagination offset (default: 0)', toOffset, 0)
     .option('--fail-fast', 'Exit 3 on first category fetch failure')
     .option('--no-color', 'Disable ANSI color (auto-disabled when not a TTY)')
     .option('--quiet', 'Suppress progress output on stderr')
@@ -117,11 +121,25 @@ export default function registerScansCommands(program, { runCmd }) {
     .command('dismissed')
     .description('List dismissed alerts for a repository')
     .requiredOption('--repo <repo>', 'Repository (owner/repo)')
-    .option('--analysis-type <type>', 'Analysis type: security|secrets (default: security)', 'security')
+    .option(
+      '--analysis-type <type>',
+      'Analysis type: security|secrets|sca|iac|antipatterns|docstring|complex_functions|dead_code|duplicate_code (default: security)',
+      'security'
+    )
     .action((opts) =>
       runCmd(() => runDismissed({ repo: opts.repo, analysisType: opts.analysisType }))
     );
 
+  // ── overrides ──────────────────────────────────────────────────────────────
+  scans
+    .command('overrides')
+    .description('List user overrides (false positive, confidence, severity) for a repository')
+    .requiredOption('--repo <repo>', 'Repository (owner/repo)')
+    .option('--analysis-type <type>', 'Analysis type: security|secrets|iac|sca (default: security)', 'security')
+    .action((opts) =>
+      runCmd(() => runOverrides({ repo: opts.repo, analysisType: opts.analysisType }))
+    );
+
   // ── start-scan ─────────────────────────────────────────────────────────────
   scans
     .command('start-scan')

package/src/commands/scans/lib/categories.js

@@ -10,6 +10,7 @@ import {
   fetchSecretsResults,
   fetchIacResults,
   fetchDeadCodeResults,
+  fetchDuplicateCodeResults,
 } from '../../../scans/fetchAdvancedScanResults.js';
 
 /**
@@ -26,6 +27,7 @@ export const CATEGORIES = {
   secrets:           { fetcher: fetchSecretsResults,          kind: 'secret' },
   iac:               { fetcher: fetchIacResults,              kind: 'config' },
   dead_code:         { fetcher: fetchDeadCodeResults,         kind: 'code' },
+  duplicate_code:    { fetcher: fetchDuplicateCodeResults,    kind: 'code' },
 };
 
 /**

package/src/commands/scans/lib/normalize.js

@@ -87,6 +87,20 @@ export function normalizeIssue(issue, category) {
   } else if (category === 'sca') {
     if (issue.cvss_score !== undefined) metadata.cvss_score = issue.cvss_score;
     if (issue.fix_version) metadata.fix_version = issue.fix_version;
+  } else if (category === 'duplicate_code') {
+    if (issue.duplicate_group !== undefined) metadata.duplicate_group = issue.duplicate_group;
+    if (issue.duplicate_locations) metadata.duplicate_locations = issue.duplicate_locations;
+  }
+
+  // Backend dispositions, present when dismissed / false positives are not filtered out.
+  if (issue.is_dismissed === true) {
+    metadata.dismissed = true;
+    if (issue.reason_for_dismiss) metadata.reason_for_dismiss = issue.reason_for_dismiss;
+    if (issue.comment_for_dismiss) metadata.comment_for_dismiss = issue.comment_for_dismiss;
+  }
+  // Secrets from older backends only carry the FALSE_POSITIVE confidence.
+  if (issue.is_false_positive === true || String(issue.confidence_score || '').toUpperCase() === 'FALSE_POSITIVE') {
+    metadata.false_positive = true;
   }
 
   const id = buildId(category, filePath, lineNumber, checkId, message);

package/src/commands/scans/results.js

@@ -30,6 +30,7 @@ export async function runResults(opts = {}) {
     limit = 100,
     offset = 0,
     failFast = false,
+    returnEnvelope = false,
   } = opts;
 
   if (!repo) {
@@ -145,7 +146,8 @@ export async function runResults(opts = {}) {
     });
   }
 
-  // 10. Render + emit
+  // 10. Render + emit (MCP callers take the envelope instead of stdout)
+  if (returnEnvelope) return envelope;
   const rendered = formatter.render(envelope);
   emit(rendered, outputPath, envelope.findings.length);
 }

package/src/index.js

@@ -20,6 +20,7 @@ import ScanCenter from './components/ScanCenter.js';
 import Welcome from './components/Welcome.js';
 import * as scm from './scm/index.js';
 import { setConfigValue } from './utils/config.js';
+import { intOption } from './utils/intOption.js';
 import { track, shutdown as analyticsShutdown, isTelemetryDisabled } from './utils/analytics.js';
 import registerScansCommands from './commands/scans/index.js';
 import registerSettingsCommands from './commands/settings/index.js';
@@ -31,6 +32,9 @@ import registerFindingsCommands from './commands/findings/index.js';
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
 
+const toCount = intOption({ min: 1 });
+const toOffset = intOption();
+
 // Split comma-separated globs while preserving commas inside {} brace expansions (e.g. "*.{js,ts}")
 function splitGlobs(input) {
   const parts = [];
@@ -67,7 +71,7 @@ program
   .option('--uncommitted', 'Scan only uncommitted changes (staged + unstaged + untracked)')
   .option('--staged', 'Scan only staged files')
   .option('--last-commit', 'Scan last commit')
-  .option('--last-n-commits <n>', 'Scan last n commits (max 5)', parseInt)
+  .option('--last-n-commits <n>', 'Scan last n commits (max 5)', toCount)
   .option('--base <branch>', 'Compare against a specific base branch (e.g. --base develop)')
   .option('--base-commit <commit>', 'Compare against a specific commit (e.g. --base-commit HEAD~3)')
   .option('--include <paths>', 'Comma-separated list of file paths glob patterns to include')
@@ -118,7 +122,7 @@ program
   .option('--uncommitted', 'Review only uncommitted changes (staged + unstaged + untracked)')
   .option('--staged', 'Review only staged files')
   .option('--last-commit', 'Review last commit')
-  .option('--last-n-commits <n>', 'Review last n commits (max 5)', parseInt)
+  .option('--last-n-commits <n>', 'Review last n commits (max 5)', toCount)
   .option('--base <branch>', 'Compare against a specific base branch (e.g. --base develop)')
   .option('--base-commit <commit>', 'Compare against a specific commit (e.g. --base-commit HEAD~3)')
   .option('--fail-on <level>', 'Fail on issues at or above this level: BLOCKER, CRITICAL, MAJOR, MINOR, INFO (default: CRITICAL)', 'CRITICAL')
@@ -299,8 +303,8 @@ program
     .option('--source-branch <branch>', 'Filter by source branch (partial match)')
     .option('--author <login>', 'Filter by author (fuzzy match)')
     .option('--state <state>', 'open or closed (default: open)', 'open')
-    .option('--limit <n>', 'Max results (default: 20, max: 100)', parseInt, 20)
-    .option('--offset <n>', 'Pagination offset', parseInt, 0)
+    .option('--limit <n>', 'Max results (default: 20, max: 100)', intOption({ min: 1, max: 100 }), 20)
+    .option('--offset <n>', 'Pagination offset', toOffset, 0)
     .action((options) => {
       const opts = resolveRepoOpts(options);
       runCmd(() => scm.listPullRequests({
@@ -315,7 +319,7 @@ program
     .option('--name <repo>', 'Repository (owner/repo)')
     .option('--remote <provider>', 'github, gitlab, bitbucket, azure')
     .option('--default-branch <branch>', 'Default branch name')
-    .requiredOption('--pr-number <n>', 'PR number', parseInt)
+    .requiredOption('--pr-number <n>', 'PR number', toCount)
     .action((options) => {
       const opts = resolveRepoOpts(options);
       runCmd(() => scm.getPullRequest({
@@ -329,7 +333,7 @@ program
     .option('--name <repo>', 'Repository (owner/repo)')
     .option('--remote <provider>', 'github, gitlab, bitbucket, azure')
     .option('--default-branch <branch>', 'Default branch name')
-    .requiredOption('--pr-number <n>', 'PR number', parseInt)
+    .requiredOption('--pr-number <n>', 'PR number', toCount)
     .option('--codeant-generated <bool>', 'Filter by CodeAnt authorship (true/false)', (v) => v === 'true')
     .option('--addressed', 'Filter by addressed/resolved status')
     .option('--created-after <date>', 'ISO 8601 date filter')
@@ -347,8 +351,8 @@ program
     .description('Resolve a conversation/comment thread on a PR')
     .option('--name <repo>', 'Repository (owner/repo)')
     .option('--remote <provider>', 'github, gitlab, bitbucket, azure')
-    .requiredOption('--pr-number <n>', 'PR number', parseInt)
-    .option('--comment-id <id>', 'Comment ID (GitHub, Bitbucket)', parseInt)
+    .requiredOption('--pr-number <n>', 'PR number', toCount)
+    .option('--comment-id <id>', 'Comment ID (GitHub, Bitbucket)', toCount)
     .option('--thread-id <id>', 'Thread/node ID (GitHub GraphQL, Azure)')
     .option('--discussion-id <id>', 'Discussion ID (GitLab)')
     .action((options) => {
@@ -370,10 +374,10 @@ program
     .option('--name <repo>', 'Repository (owner/repo)')
     .option('--remote <provider>', 'github, gitlab, bitbucket, azure')
     .option('--default-branch <branch>', 'Default branch name')
-    .option('--pr-number <n>', 'Filter by PR number', parseInt)
+    .option('--pr-number <n>', 'Filter by PR number', toCount)
     .option('--status <status>', 'Filter by status (PENDING, COMPLETED, FAILED, etc.)')
-    .option('--limit <n>', 'Max results (default: 20)', parseInt, 20)
-    .option('--offset <n>', 'Pagination offset', parseInt, 0)
+    .option('--limit <n>', 'Max results (default: 20)', toCount, 20)
+    .option('--offset <n>', 'Pagination offset', toOffset, 0)
     .action((options) => {
       const opts = resolveRepoOpts(options);
       runCmd(() => scm.listCodeReviews({
@@ -387,7 +391,7 @@ program
     .description('Get detailed information for a specific code review')
     .option('--name <repo>', 'Repository (owner/repo)')
     .option('--remote <provider>', 'github, gitlab, bitbucket, azure')
-    .requiredOption('--pr-number <n>', 'PR number', parseInt)
+    .requiredOption('--pr-number <n>', 'PR number', toCount)
     .requiredOption('--review-id <id>', 'Code review ID')
     .action((options) => {
       const opts = resolveRepoOpts(options);
@@ -405,7 +409,7 @@ program
     .option('--name <repo>', 'Repository (owner/repo)')
     .option('--remote <provider>', 'github, gitlab, bitbucket, azure')
     .requiredOption('--query <term>', 'Search term')
-    .option('--limit <n>', 'Max results (default: 10, max: 50)', parseInt, 10)
+    .option('--limit <n>', 'Max results (default: 10, max: 50)', intOption({ min: 1, max: 50 }), 10)
     .option('--include-addressed', 'Include resolved comments (default: false)')
     .option('--created-after <date>', 'ISO 8601 date filter')
     .action((options) => {