kastell 2.2.6 → 2.3.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kastell",
-  "version": "2.2.5",
-  "description": "Server security auditing, hardening, and fleet management. 457 security checks across 30 categories, CIS/PCI-DSS/HIPAA compliance, 24-step production hardening, and 17 MCP tools. Supports Hetzner, DigitalOcean, Vultr, Linode with Coolify, Dokploy, and bare VPS modes.",
+  "version": "2.3.0",
+  "description": "Server security auditing, hardening, and fleet management. 470+ security checks across 32 categories, CIS/PCI-DSS/HIPAA compliance, 24-step production hardening, and 17 MCP tools. Supports Hetzner, DigitalOcean, Vultr, Linode with Coolify, Dokploy, and bare VPS modes.",
   "author": {
     "name": "kastelldev",
     "email": "hello@omrfc.dev",
@@ -32,7 +32,9 @@
   "mcpServers": {
     "kastell": {
       "command": "node",
-      "args": ["${CLAUDE_PLUGIN_ROOT}/dist/mcp-bundle.mjs"],
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/dist/mcp-bundle.mjs"
+      ],
       "env": {
         "HETZNER_TOKEN": "${HETZNER_TOKEN}",
         "DIGITALOCEAN_TOKEN": "${DIGITALOCEAN_TOKEN}",

package/CHANGELOG.md

@@ -2,6 +2,118 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.3.0] - 2026-06-12
+
+### Added
+- **`markCommandFailed()` exit code helper** — `src/utils/exitCode.ts` centralizes `process.exitCode = 1` signaling; adopted across `snapshot`, `domain`, `maintain`, `update`, `audit`, `evidence`, `fix`, `init` commands (P141)
+- **`isolatedKastellEnv` Jest helper** — `tests/helpers/isolatedKastellEnv.ts` provides per-test `KASTELL_DIR` isolation with self-registering `afterEach` cleanup (P141)
+- **Atomic `*.tmp` rename helpers** — `atomicWriteFileSync`, `fsRetry`, `secureAppendFileSync` for Windows-safe persistence with `EPERM`/`EACCES` retry + copy+unlink fallback (P140)
+- **MCP `startupDiagnostic` helper** — `src/mcp/startupDiagnostic.ts` reports SDK + build identity at MCP boot (P141)
+- **`fileLock` structured return** — `assessLockState` returns owner PID hash + `ownerHost="internal"` for safe diagnostic surfacing; stale-lock reclaim now re-acquires the lock and runs `fn()` when removal succeeds (P141)
+- Plugin checks now run in parallel (cap=3, configurable via `PLUGIN_AUDIT_PARALLELISM`)
+- Aggregate timeout for plugin audit (`PLUGIN_AUDIT_TOTAL_TIMEOUT_MS`, default 120s)
+- `safeToParallel: false` opt-out in plugin manifest for plugins with intentional mutating checkCommands
+- File-mtime cache for `getServers()` and `loadLatestAudit(ip)` with network FS guard
+- MCP SDK round-trip test for serverCompare schema
+- Plugin tarball smoke test: MCP boot time measurement + empty dir detection
+
+### Changed
+- Breaking: Plugin SDK audit checks now require `apiVersion: "2"` and object-shaped `checkCommand: { kind, cmd }`. Manifest-level `mutates` and `safeToParallel` are removed; mutation intent is declared per check.
+- **`chunkConcurrent`** replaces `p-limit` in fleet.ts (p-limit dependency dropped)
+- `serverCompare` outputSchema uses `discriminatedUnion` (dış shape aynı kalır)
+- `PluginRegistryEntry` is now a discriminated union (loaded/error/disabled)
+- CI workflow: build artifact shared between jobs (~30s saving per run)
+- **`fileLock` reclaim now re-acquires the lock and runs `fn()` when stale removal succeeds** — previously only recorded the reclaim error and gave up (P141 Codex gap)
+- **Explicit `process.env[PROVIDER_TOKEN]` overrides buffered/keychain tokens** — prevents stale desktop keychain entries from breaking MCP/container calls (P141 Codex gap)
+- **`server_info` health outputSchema** — single-server fields (`server`, `ip`, `mode`, `sshReachable`, `hostKeyMismatch`, `platformStatus`, `coolifyUrl`, `dokployUrl`) now part of the schema; `results`/`summary` optional for per-server response (P141 Codex gap)
+
+Release-time version bumps remain owned by `/release minor`; `package.json` and `kastell-plugin/.claude-plugin/plugin.json` must be bumped together.
+
+### Fixed
+- `serverCompare` detail mode returns flat checks array (was object — CQS-11 #1)
+- `ssh-factories.ts` setTimeout leak — worker force-exit (CQS-10 #1)
+- `tests/helpers/fsMock.ts` factory prevents Linux CI chmodSync mock omission
+- Explicit provider token environment variables now override buffered and keychain credentials, preventing stale desktop keychain entries from breaking MCP/container calls.
+- Single-server `server_info health` responses now validate against the registered MCP output schema.
+- **Windows local state writes** — Atomic `*.tmp` rename persistence now retries transient `EPERM`/`EACCES` failures and falls back to copy+unlink safely. Coverage: `servers.json`, audit history, evidence manifests (`MANIFEST.json`, `SHA256SUMS`), audit snapshots, fix history, regression baselines, and metric history. File-lock reclaim and security-log rotation also retry on transient `EPERM`/`EACCES`.
+- **Status command error path exits 1** via `markCommandFailed()` — partial failures now propagate non-zero exit code matching other reliability contracts (P141)
+- **Audit `--json` and `--ci` stdout parse-clean** — no log pollution; reserved for a single JSON payload (P141)
+- **Windows file-lock diagnostics** for persistent `EPERM`/`EACCES` — hint-rich surface, replaces "transient" claim (P141)
+- **`printDiff` regression path** unconditionally marks `process.exitCode = 1` (P141 `/simplify`)
+
+### Internal
+- 175 `console.log` triage + sweep (5 categories — 0 actionable)
+- 13 slow tests audit (P140 input)
+- `createFsMock` factory adopted across 32 test files
+- `McpServerInternal` named type (CQS-05)
+- `serverCompare` eslint-disable orphan cleanup (CQS-10 #2)
+
+### BREAKING
+- `server_fix` MCP input shape changed: `dryRun: boolean` removed, replaced by `mode: 'dry-run' | 'live'` on the `apply` action branch. CLI users unaffected (`--dry-run` flag unchanged). MCP consumers must update calls.
+- `server_fix` MCP output shape changed: non-apply actions (`history`, `rollback`, `rollback-all`, `rollback-to`) no longer carry a `dryRun` field. Previously the field held the action name as a string proxy to satisfy a misnamed discriminator; now responses are discriminated by `action` and `dryRun: boolean` appears only on `apply` responses where it semantically belongs.
+- `server_secure firewall-status` MCP output: `rules` is now `z.array(z.object({port, proto, action, from}))` (object array) instead of `z.array(z.string())` (string array). SDK probe confirms: MCP SDK strips `structuredContent` on outputSchema mismatch. Hard-cut BREAKING. (F-020)
+
+### Fixed
+- `server_secure` action `audit` added as canonical name. `secure-audit` still accepted (deprecated, removal scheduled for v2.4) (F-011)
+- `server_info status` `summary.running` correctly counts running servers when either `serverStatus` (cloud provider) or `platformStatus` (Coolify/Dokploy) is "running". Previously only checked `platformStatus`, missing servers where the cloud reports running but the platform probe fails. (F-024)
+- `server_guard status` returns `success: boolean` and `logTail: string[]` (line array). (F-022)
+- `server_logs monitor` returns structured `metrics.{cpu,mem,disk}` objects (bytes for total/used, IEC binary) instead of validation-failing strings. CLI output unchanged. (F-019)
+- `server_backup backup-list` returns `backupCount` field (F-021)
+- `kastell audit` accepts `--framework <cis-level1|cis-level2|pci-dss|hipaa>` (parity with MCP) (F-016)
+- Keychain decrypt warnings now deduplicate into single line with provider list (CQS-07)
+- Audit `--threshold` and all early-return paths now correctly set `process.exitCode = 1` via AuditError policy (F-015)
+- `kastell add --skip-verify` now respects `--mode coolify|bare` flag (F-002)
+- `kastell lock --dry-run` error message clarified (F-010)
+- `kastell fix --dry-run` requires `--safe` with clear error (F-012)
+- `kastell fix --history` shows informative empty state (F-014)
+- Bash completions synced with command registry (F-025)
+
+### Changed
+- MCP server tool registration refactored to iterate `ALL_MCP_TOOLS` (~340 lines removed)
+- Plugin audit checks now parallelize (max 4 per host) with AbortController-based aggregate timeout (CQS-06)
+- Fixture `makeServerRecord` helper extracted across 10 fixtures (~100 lines saved)
+- `isWindows()` helper extracts 6 inline platform checks
+
+### Added
+- Regression test for `server_plugin list` reading from the loaded plugin registry (fix landed in v2.2.0 P134c/d; test prevents future drift, F-018)
+- `AuditError` class for centralized audit error handling
+- `chunkConcurrent` helper for bounded parallel work
+- `PluginSeverity` / `FixTier` shared types
+- `Safety Modes` section in README
+- `kastell provision` alias for `init`
+
+### v2.3 Reliability Contracts
+
+- **Immediate MCP durable registration** — `server_provision` returns as soon as the provider creates the server and Kastell durably persists the record. `readiness.status` may be `pending`; follow with `server_info status` or `server_info health`.
+- **Verified CLI failures return non-zero** — unsupported and failed CLI operations exit with `1`; valid empty results and user cancellation exit with `0`. Mixed `--all` failures exit with `1`.
+- **Parse-clean audit stdout** — `audit --json` and `audit --ci` reserve stdout for a single JSON payload.
+- **Actionable Windows lock diagnostics** — persistent `EPERM`/`EACCES` failures on Windows file-lock paths now surface hint-rich diagnostics.
+- **MCP SDK round-trip coverage** — `server_manage add/remove/destroy` outputSchemas now have full `normalizeObjectSchema` + `safeParseAsync` round-trip tests.
+
+### Security
+
+- **Notify webhook SSRF hardening (HIGH-001)** — Discord/Slack webhook connections now reject private/reserved IPv4 and IPv6 targets during the actual socket DNS lookup, pin connections to validated public answers, and disable redirects and environment proxies.
+- **Reclassified P142 security follow-ups (reviewed 2026-06-12):**
+  - **MEDIUM** — `starter` CLI template skips the optional extra SSH hardening step. Platform cloud-init still configures firewall rules; bare mode also installs fail2ban and unattended-upgrades.
+  - **MEDIUM** — SSH `StrictHostKeyChecking=accept-new` carries first-connection TOFU risk; strict host-key handling needs separate policies for interactive SSH and newly provisioned servers.
+  - **LOW** — `debugLog` does not detect raw secret-shaped strings, though current core error-object call sites are collapsed to `[object]`.
+  - **LOW / operational** — CLI safe mode defaults off for trusted local operation; non-TTY automation can still benefit from safer defaults or warnings.
+- **Removed from the security backlog** — Ubuntu 24.04 provider pinning is a provisioning reliability policy, not a security vulnerability; the previously documented DigitalOcean SSH issue has dedicated cloud-init mitigations.
+
+## [Unreleased]
+
+## [2.2.7] - 2026-05-16
+
+### Fixed
+- **npm tarball plugin.json version sync** — v2.2.6 npm tarball shipped with `package.json` 2.2.6 but `.claude-plugin/plugin.json` stuck at 2.2.5; CC marketplace `/plugin update` showed correct version on disk but plugin manifest reported stale. Release flow now syncs `plugin.json` **before** `npm version` and validates tarball contents **before** push (FATAL gate). Users now see correct version after `/plugin update`.
+
+### Added
+- **Plugin tarball smoke test (`scripts/smoke-plugin-install.sh`)** — simulates CC plugin install (no `npm install`): runs `npm pack`, extracts tarball, verifies all manifest paths shipped, and boots MCP bundle without module errors
+- **CI `plugin-manifest` job** — schema validation + version drift detection + smoke test on Ubuntu/Node 20 (catches plugin shipping issues before publish)
+
+### Changed
+- **Test mock race fix** — `process.nextTick` replaces `setTimeout(_, 5)` for stderr emit in `mockProcess.ts`, `mcp-server-backup.test.ts`, `restore.test.ts`; eliminates flaky `scpDownload` timing race on macOS-Node20 CI runners (5ms stderr vs 10ms close ordering)
+
 ## [2.2.6] - 2026-05-16
 
 ### Added

package/README.md

@@ -46,7 +46,7 @@ Running `kastell` without any arguments launches an **interactive search menu**
  ██║  ██╗  ██║  ██║ ███████║   ██║   ███████╗███████╗███████╗
  ╚═╝  ╚═╝  ╚═╝  ╚═╝ ╚══════╝   ╚═╝   ╚══════╝╚══════╝╚══════╝
 
-  KASTELL  v2.2.6  ·  Your infrastructure, fortified.
+  KASTELL  v2.3.0  ·  Your infrastructure, fortified.
 
   $ kastell init --template production  → deploy a new server
   $ kastell status --all                → check all servers
@@ -95,9 +95,9 @@ Kastell handles server provisioning, SSH key setup, firewall configuration, and
 |---------|---------|-------|----------|
 | Installation | `npm i -g kastell` | Package manager | Package manager |
 | Language | TypeScript | Shell | C/Python |
-| Security Checks | 457+ | 300+ | Varies by profile |
+| Security Checks | 470+ | 300+ | Varies by profile |
 | Auto-Fix | Safe tier | Suggest only | Suggest only |
-| MCP (AI Agent) | 14 tools | -- | -- |
+| MCP (AI Agent) | 17 tools | -- | -- |
 | Compliance | CIS, PCI-DSS, HIPAA | CIS, HIPAA | CIS, STIG, PCI-DSS |
 | Cloud Provision | 4 providers | -- | -- |
 | Hardening (Lock) | 24-step | -- | -- |
@@ -170,7 +170,7 @@ kastell domain add my-server --domain example.com  # Set domain + SSL
 
 ### Security Audit
 ```bash
-kastell audit my-server                  # Full security audit (31 categories, 468+ checks)
+kastell audit my-server                  # Full security audit (32 categories, 470+ checks)
 kastell audit my-server --json           # JSON output for automation
 kastell audit my-server --threshold 70   # Exit code 1 if score below threshold
 kastell audit my-server --fix            # Interactive fix mode (prompts per severity)
@@ -263,7 +263,7 @@ kastell init --template production --provider hetzner
 
 ## Security
 
-Kastell is built with security as a priority -- **9,871 tests** across 219 suites, including dedicated security test suites.
+Kastell is built with security as a priority -- **11,206 tests** across 344 suites, including dedicated security test suites.
 
 - API tokens are never stored on disk -- prompted at runtime or via environment variables
 - SSH keys are auto-generated if needed (Ed25519)
@@ -291,6 +291,16 @@ kastell <command>
 
 Requires Node.js 20 or later.
 
+## Safety Modes
+
+`KASTELL_SAFE_MODE` environment variable controls destructive operations:
+
+- **MCP default:** `true` — `provision`, `destroy`, `restore` are blocked
+- **CLI default:** `false` — all operations are enabled
+- **Override:** `KASTELL_SAFE_MODE=true kastell destroy <server>` → rejected
+
+Affected commands: `init`, `destroy`, `backup-restore`, `snapshot-restore`, `snapshot-delete`, `restart`, `maintain`.
+
 ## Troubleshooting
 
 **Server creation fails?**
@@ -306,7 +316,7 @@ Use `kastell status my-server --autostart` to check platform status and auto-res
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and contribution guidelines.
 
-Kastell uses **9,871 tests** across 219 suites. Run `npm test` before submitting PRs.
+Kastell uses **11,206 tests** across 344 suites. Run `npm test` before submitting PRs.
 
 ## MCP Server (AI Integration)
 
@@ -375,6 +385,24 @@ Install via Claude Code plugin manager or use directly with `claude --plugin-dir
 
 Kastell provides [`llms.txt`](llms.txt) for AI crawlers and is listed in the [MCP Registry](https://registry.modelcontextprotocol.io/) as `io.github.kastelldev/kastell`.
 
+## v2.3 Reliability Contracts
+
+These contracts apply to the CLI and the MCP server.
+
+### Provisioning behavior
+
+`server_provision` returns after the provider creates the server and Kastell
+durably registers it. `readiness.status` may be `pending`; follow with
+`server_info status` or `server_info health`. The interactive `kastell init`
+command continues waiting through its existing readiness checks.
+
+### Automation contracts
+
+- Unsupported and failed CLI operations return exit code `1`.
+- Valid empty results and user cancellation return `0`.
+- Mixed `--all` failures return `1`.
+- `audit --json` and `audit --ci` reserve stdout for one JSON payload.
+
 ## CI/CD Integration
 
 Use `kastell audit` in your CI pipeline to enforce security baselines:

package/README.tr.md

@@ -46,7 +46,7 @@ npx kastell
  ██║  ██╗  ██║  ██║ ███████║   ██║   ███████╗███████╗███████╗
  ╚═╝  ╚═╝  ╚═╝  ╚═╝ ╚══════╝   ╚═╝   ╚══════╝╚══════╝╚══════╝
 
-  KASTELL  v2.2.4  ·  Your infrastructure, fortified.
+  KASTELL  v2.3.0  ·  Your infrastructure, fortified.
 
   $ kastell init --template production  → deploy a new server
   $ kastell status --all                → check all servers
@@ -95,9 +95,9 @@ Kastell sunucu oluşturma, SSH anahtar kurulumu, güvenlik duvarı yapılandırm
 |---------|---------|-------|----------|
 | Kurulum | `npm i -g kastell` | Paket yoneticisi | Paket yoneticisi |
 | Dil | TypeScript | Shell | C/Python |
-| Guvenlik Kontrolleri | 457+ | 300+ | Profile gore degisir |
+| Guvenlik Kontrolleri | 470+ | 300+ | Profile gore degisir |
 | Otomatik Duzeltme | Guvenli katman | Sadece oneri | Sadece oneri |
-| MCP (AI Ajan) | 14 arac | -- | -- |
+| MCP (AI Ajan) | 17 arac | -- | -- |
 | Uyumluluk | CIS, PCI-DSS, HIPAA | CIS, HIPAA | CIS, STIG, PCI-DSS |
 | Bulut Saglama | 4 saglayici | -- | -- |
 | Siklastirma (Lock) | 24 adim | -- | -- |
@@ -170,7 +170,7 @@ kastell domain add sunucum --domain ornek.com  # Domain + SSL ayarla
 
 ### Güvenlik Denetimi
 ```bash
-kastell audit sunucum                    # Tam güvenlik denetimi (31 kategori, 468+ kontrol)
+kastell audit sunucum                    # Tam güvenlik denetimi (32 kategori, 470+ kontrol)
 kastell audit sunucum --json             # Otomasyon için JSON çıktısı
 kastell audit sunucum --threshold 70     # Skor eşiğin altındaysa exit code 1
 kastell audit sunucum --fix              # İnteraktif düzeltme modu (önem derecesine göre)
@@ -263,7 +263,7 @@ kastell init --template production --provider hetzner
 
 ## Güvenlik
 
-Kastell güvenlik öncelikli olarak geliştirilmektedir -- 219 test suite'inde **9.871 test**, özel güvenlik test suite'leri dahil.
+Kastell güvenlik öncelikli olarak geliştirilmektedir -- 344 test suite'inde **11.206 test**, özel güvenlik test suite'leri dahil.
 
 - API token'ları asla diske kaydedilmez -- çalışma zamanında sorulur veya ortam değişkenlerinden alınır
 - SSH anahtarları gerekirse otomatik oluşturulur (Ed25519)
@@ -306,7 +306,7 @@ Platform durumunu kontrol edip gerekirse otomatik yeniden başlatmak için `kast
 
 Geliştirme ortamı kurulumu, test ve katkı rehberi için [CONTRIBUTING.md](CONTRIBUTING.md) dosyasına bakın.
 
-Kastell, 207 suite'te **6.441 test** kullanmaktadır. PR göndermeden önce `npm test` çalıştırın.
+Kastell, 344 suite'te **11.206 test** kullanmaktadır. PR göndermeden önce `npm test` çalıştırın.
 
 ## MCP Sunucusu (Yapay Zeka Entegrasyonu)
 

package/dist/commands/audit.d.ts

@@ -19,14 +19,15 @@ export interface AuditCommandOptions extends AuditCliOptions {
     days?: string;
     listChecks?: boolean;
     profile?: string;
+    framework?: string;
     compliance?: string;
     fresh?: boolean;
     detail?: boolean;
     ci?: boolean;
 }
 /**
- * Execute the audit command.
- * Flow: resolveServer (or parse --host) -> runAudit -> select formatter -> output -> threshold check
+ * Wrapper: catches AuditError and sets exitCode = 1.
+ * All early-return paths in auditCommandImpl throw AuditError instead.
  */
 export declare function auditCommand(serverName?: string, options?: AuditCommandOptions): Promise<void>;
 //# sourceMappingURL=audit.d.ts.map

package/dist/commands/audit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/commands/audit.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAoBH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAczE,MAAM,WAAW,mBAAoB,SAAQ,eAAe;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC5B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,EAAE,CAAC,EAAE,OAAO,CAAC;CACd;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,IAAI,CAAC,CAiXf"}
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/commands/audit.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAqBH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAgBzE,MAAM,WAAW,mBAAoB,SAAQ,eAAe;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC5B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,EAAE,CAAC,EAAE,OAAO,CAAC;CACd;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,IAAI,CAAC,CAWf"}

package/dist/commands/audit.js

@@ -22,17 +22,54 @@ import { FRAMEWORK_KEY_MAP } from "../core/audit/compliance/types.js";
 import { filterAuditResult, buildFilterAnnotation, parseSeverity } from "../core/audit/filter.js";
 import { saveBaselineSafe, loadBaseline, checkRegression, formatRegressionSummary, extractPassedCheckIds, shouldUpdateBaseline } from "../core/audit/regression.js";
 import { loadDefaults } from "../core/defaults.js";
+import { AuditError } from "../core/audit/errors.js";
+import { markCommandFailed } from "../utils/exitCode.js";
 function printDiff(diff, json) {
     console.log(json ? formatDiffJson(diff) : formatDiffTerminal(diff));
     if (diff.regressions.length > 0) {
-        process.exitCode = 1;
+        markCommandFailed();
+    }
+}
+/**
+ * Wrapper: catches AuditError and sets exitCode = 1.
+ * All early-return paths in auditCommandImpl throw AuditError instead.
+ */
+export async function auditCommand(serverName, options = {}) {
+    try {
+        await auditCommandImpl(serverName, options);
+    }
+    catch (err) {
+        if (err instanceof AuditError) {
+            logger.error(err.message);
+            markCommandFailed();
+            return;
+        }
+        throw err;
     }
 }
 /**
  * Execute the audit command.
  * Flow: resolveServer (or parse --host) -> runAudit -> select formatter -> output -> threshold check
  */
-export async function auditCommand(serverName, options = {}) {
+async function auditCommandImpl(serverName, options = {}) {
+    if (options.ci) {
+        options.json = true;
+    }
+    const machineOutput = options.json === true || options.ci === true;
+    const logDiagnostic = (severity, message) => {
+        if (machineOutput) {
+            process.stderr.write(`${message}\n`);
+        }
+        else if (severity === "warning") {
+            logger.warning(message);
+        }
+        else if (severity === "success") {
+            logger.success(message);
+        }
+        else {
+            logger.info(message);
+        }
+    };
     // --list-checks: static catalog display — no SSH connection needed
     if (options.listChecks) {
         const filter = {};
@@ -62,12 +99,8 @@ export async function auditCommand(serverName, options = {}) {
         }
     }
     // --ci mode: validate threshold requirement early (before server resolution)
-    if (options.ci) {
-        if (options.threshold === undefined) {
-            logger.error("--ci requires --threshold (e.g. --ci --threshold 70)");
-            return;
-        }
-        options.json = true;
+    if (options.ci && options.threshold === undefined) {
+        throw new AuditError("--ci requires --threshold (e.g. --ci --threshold 70)");
     }
     let ip;
     let name;
@@ -130,19 +163,16 @@ export async function auditCommand(serverName, options = {}) {
     if (options.diff) {
         const parts = options.diff.split(":");
         if (parts.length !== 2) {
-            logger.error("--diff requires format: before:after (e.g. pre-upgrade:latest)");
-            return;
+            throw new AuditError("--diff requires format: before:after (e.g. pre-upgrade:latest)");
         }
         const [beforeRef, afterRef] = parts;
         const beforeSnap = await resolveSnapshotRef(ip, beforeRef);
         const afterSnap = await resolveSnapshotRef(ip, afterRef);
         if (!beforeSnap) {
-            logger.error(`Snapshot not found: ${beforeRef}`);
-            return;
+            throw new AuditError(`Snapshot not found: ${beforeRef}`);
         }
         if (!afterSnap) {
-            logger.error(`Snapshot not found: ${afterRef}`);
-            return;
+            throw new AuditError(`Snapshot not found: ${afterRef}`);
         }
         const diff = diffAudits(beforeSnap.audit, afterSnap.audit, {
             before: beforeSnap.name ?? beforeRef,
@@ -155,28 +185,24 @@ export async function auditCommand(serverName, options = {}) {
     if (options.compare) {
         const parts = options.compare.split(":");
         if (parts.length !== 2) {
-            logger.error("--compare requires format: server1:server2");
-            return;
+            throw new AuditError("--compare requires format: server1:server2");
         }
         const [serverARef, serverBRef] = parts;
         const servers = getServers();
         const serverA = servers.find((s) => s.name === serverARef || s.ip === serverARef);
         const serverB = servers.find((s) => s.name === serverBRef || s.ip === serverBRef);
         if (!serverA) {
-            logger.error(`Server not found: ${serverARef}`);
-            return;
+            throw new AuditError(`Server not found: ${serverARef}`);
         }
         if (!serverB) {
-            logger.error(`Server not found: ${serverBRef}`);
-            return;
+            throw new AuditError(`Server not found: ${serverBRef}`);
         }
         const spinner = createSpinner("Comparing servers...");
         spinner.start();
         const pairResult = await resolveAuditPair(serverA, serverB, !!options.fresh);
         spinner.stop();
         if (!pairResult.success) {
-            logger.error(pairResult.error ?? "Compare failed");
-            return;
+            throw new AuditError(pairResult.error ?? "Compare failed");
         }
         const { auditA, auditB } = pairResult.data;
         if (options.detail) {
@@ -193,8 +219,7 @@ export async function auditCommand(serverName, options = {}) {
     if (options.watch !== undefined) {
         const interval = options.watch ? parseInt(options.watch, 10) : undefined;
         if (interval !== undefined && (isNaN(interval) || interval < 1)) {
-            logger.error("Watch interval must be a positive number (seconds)");
-            return;
+            throw new AuditError("Watch interval must be a positive number (seconds)");
         }
         const formatter = await selectFormatter(options);
         logger.info(`Starting watch mode for ${name} (interval: ${interval ?? 300}s)`);
@@ -204,13 +229,13 @@ export async function auditCommand(serverName, options = {}) {
         });
         return;
     }
-    const spinner = options.ci ? null : createSpinner(`Running security audit on ${name}...`);
+    const spinner = machineOutput ? null : createSpinner(`Running security audit on ${name}...`);
     spinner?.start();
     const result = await runAudit(ip, name, platform);
     if (!result.success || !result.data) {
         spinner?.fail(result.error ?? "Audit failed");
         if (result.hint) {
-            logger.info(result.hint);
+            logDiagnostic("info", result.hint);
         }
         return;
     }
@@ -222,10 +247,10 @@ export async function auditCommand(serverName, options = {}) {
     // Save to history (after trend detection)
     await saveAuditHistory(auditResult);
     if (trend === "methodology-change") {
-        logger.warning("Score methodology updated. New baseline established.");
+        logDiagnostic("warning", "Score methodology updated. New baseline established.");
     }
     else if (trend !== "first audit") {
-        logger.info(`Trend: ${trend}`);
+        logDiagnostic("info", `Trend: ${trend}`);
     }
     const baseline = loadBaseline(auditResult.serverIp);
     const passedIds = extractPassedCheckIds(auditResult);
@@ -238,10 +263,7 @@ export async function auditCommand(serverName, options = {}) {
     }
     if (regression) {
         for (const line of formatRegressionSummary(regression)) {
-            if (line.severity === "warning")
-                logger.warning(line.text);
-            else
-                logger.info(line.text);
+            logDiagnostic(line.severity, line.text);
         }
     }
     // --compliance: detailed Framework>Control>Check grouped report
@@ -251,8 +273,7 @@ export async function auditCommand(serverName, options = {}) {
             .map((f) => FRAMEWORK_KEY_MAP[f.trim().toLowerCase()])
             .filter((f) => !!f);
         if (frameworks.length === 0) {
-            logger.error("Invalid framework. Use: cis, pci-dss, hipaa");
-            return;
+            throw new AuditError("Invalid framework. Use: cis, pci-dss, hipaa");
         }
         if (options.json) {
             const detail = calculateComplianceDetail(auditResult.categories);
@@ -264,12 +285,34 @@ export async function auditCommand(serverName, options = {}) {
         }
         return;
     }
+    // --framework: filtered audit view by single compliance framework
+    if (options.framework) {
+        const validFrameworks = ["cis-level1", "cis-level2", "pci-dss", "hipaa"];
+        if (!validFrameworks.includes(options.framework)) {
+            throw new AuditError(`Invalid framework: ${options.framework}. Valid: ${validFrameworks.join(", ")}`);
+        }
+        const fw = FRAMEWORK_KEY_MAP[options.framework];
+        const filteredResult = filterByProfile(auditResult, options.framework);
+        const detail = calculateComplianceDetail(auditResult.categories);
+        const fwScore = detail.find((d) => d.framework === fw);
+        if (options.json) {
+            const fwDetail = detail.filter((d) => d.framework === fw);
+            console.log(JSON.stringify({ overallScore: auditResult.overallScore, compliance: fwDetail }, null, 2));
+        }
+        else {
+            const formatter = await selectFormatter(options);
+            console.log(formatter(filteredResult));
+            if (fwScore) {
+                logger.info(`Framework ${options.framework}: ${fwScore.passedControls}/${fwScore.totalControls} controls (${fwScore.passRate}%)`);
+            }
+        }
+        return;
+    }
     // --profile: filtered audit view by compliance framework
     if (options.profile) {
         const validProfiles = ["cis-level1", "cis-level2", "pci-dss", "hipaa"];
         if (!validProfiles.includes(options.profile)) {
-            logger.error(`Invalid profile. Use: ${validProfiles.join(", ")}`);
-            return;
+            throw new AuditError(`Invalid profile. Use: ${validProfiles.join(", ")}`);
         }
         const profileName = options.profile;
         const filteredResult = filterByProfile(auditResult, profileName);
@@ -281,7 +324,8 @@ export async function auditCommand(serverName, options = {}) {
         const detail = calculateComplianceDetail(auditResult.categories);
         const profileScore = detail.find((d) => d.framework === profileFramework);
         if (profileScore) {
-            logger.info(`Profile ${options.profile}: ${profileScore.passedControls}/${profileScore.totalControls} controls (${profileScore.passRate}%)`);
+            const profileLine = `Profile ${options.profile}: ${profileScore.passedControls}/${profileScore.totalControls} controls (${profileScore.passRate}%)`;
+            logDiagnostic("info", profileLine);
         }
         return;
     }
@@ -289,7 +333,7 @@ export async function auditCommand(serverName, options = {}) {
     if (options.snapshot !== undefined) {
         const snapshotName = typeof options.snapshot === "string" ? options.snapshot : undefined;
         await saveSnapshot(auditResult, snapshotName);
-        logger.success(`Snapshot saved for ${name}`);
+        logDiagnostic("success", `Snapshot saved for ${name}`);
     }
     // Apply display-only filter (AUX-01, AUX-02, AUX-03)
     // MUST be after saveAuditHistory + saveSnapshot to preserve unfiltered data (AUX-04)
@@ -349,11 +393,10 @@ export async function auditCommand(serverName, options = {}) {
         if (options.threshold) {
             const threshold = parseInt(options.threshold, 10);
             if (isNaN(threshold)) {
-                logger.error("--threshold must be a number");
-                return;
+                throw new AuditError("--threshold must be a number");
             }
             if (auditResult.overallScore < threshold) {
-                process.exitCode = 1;
+                markCommandFailed();
                 return;
             }
         }
@@ -364,11 +407,11 @@ export async function auditCommand(serverName, options = {}) {
     const output = formatter(displayResult);
     console.log(output);
     // Show filter annotation when active
-    if (filterAnnotation) {
+    if (filterAnnotation && !machineOutput) {
         logger.info(`Score: ${auditResult.overallScore}/100${filterAnnotation}`);
     }
     // Show quick wins in terminal output
-    if (auditResult.quickWins.length > 0 && !options.json && !options.badge && !options.report) {
+    if (auditResult.quickWins.length > 0 && !machineOutput && !options.badge && !options.report) {
         const lastWin = auditResult.quickWins[auditResult.quickWins.length - 1];
         logger.info(`Quick wins: ${auditResult.quickWins.length} fix(es) to reach ${lastWin.projectedScore}/100`);
     }
@@ -376,12 +419,10 @@ export async function auditCommand(serverName, options = {}) {
     if (options.threshold) {
         const threshold = parseInt(options.threshold, 10);
         if (isNaN(threshold)) {
-            logger.error("--threshold must be a number");
-            return;
+            throw new AuditError("--threshold must be a number");
         }
         if (auditResult.overallScore < threshold) {
-            logger.error(`Score ${auditResult.overallScore} is below threshold ${threshold}`);
-            process.exitCode = 1;
+            markCommandFailed();
             return;
         }
     }