cloudburn 0.16.0 → 0.17.0

package/README.md

@@ -115,6 +115,27 @@ cloudburn rules list --service ec2 --source discovery --severity high
 
 The discovery config equivalent is `discovery.fail-on`.
 
+Discovery has a five-minute deadline. Use `--timeout <seconds>` to change it, for example `cloudburn discover --timeout 600`. If the deadline expires, the command exits with code 2 and reports the timeout.
+
+Discovery reuses fresh, complete evidence from a per-user cache at `$XDG_CACHE_HOME/cloudburn/evidence`, or
+`~/.cache/cloudburn/evidence` when `XDG_CACHE_HOME` is unset. Rules and configuration are evaluated on every run.
+
+```bash
+cloudburn discover --cache refresh
+cloudburn discover --cache off
+cloudburn discover --cache-dir /path/to/evidence --cache-context policy-revision-2
+```
+
+`--cache refresh` collects current evidence and never silently falls back when collection fails. `--cache off` bypasses
+persistent reads and writes. Customer evidence reuse requires a safe temporary AWS credential session scope or an
+explicit `--cache-context` identifying the effective authorization and session-policy revision. An account ID or role
+ARN alone is insufficient. Change the context when permissions change. Public pricing is cached independently of
+customer evidence, and credentials are never stored.
+
+Table output includes a freshness summary; `--format json` includes full evidence provenance and coverage. TTLs are
+tunable starting policies rather than measured optimal defaults. See the [cache options](../../docs/reference/commands.md#discovery-evidence-cache)
+and [SDK README](../sdk/README.md) for modes, defaults, and freshness tradeoffs.
+
 The CLI targets one region per run. Multi-region discovery remains available through the SDK and still needs an AWS Resource Explorer aggregator plus an unfiltered default view in the aggregator region.
 `CLDBRN-AWS-TAGGING-1` is opt-in and requires an accessible aggregator; a local-only setup cannot run account-wide tagging discovery.
 `CLDBRN-AWS-LAMBDA-4` is opt-in and requires AWS Compute Optimizer enrollment.

package/dist/cli.js

@@ -654,20 +654,34 @@ ${regionsTable}`;
       const findingRows = projectFindingRows(response.result);
       const diagnosticRows = projectDiagnosticRows(response.result);
       const suppressedCount = response.result.suppressed?.length ?? 0;
-      const withSuppressedCount = (content) => suppressedCount > 0 ? `${content}
-
-Suppressed: ${suppressedCount}` : content;
+      const withScanSummary = (content) => {
+        const sections = [content];
+        if (suppressedCount > 0) {
+          sections.push(`Suppressed: ${suppressedCount}`);
+        }
+        const evidence = response.result.evidence ?? [];
+        if (evidence.length > 0) {
+          const cachedCount = evidence.filter((entry) => entry.source === "cache").length;
+          const incompleteCount = evidence.filter((entry) => !entry.complete).length;
+          const oldestObservation = evidence.map((entry) => entry.observedAt).sort()[0];
+          sections.push(
+            `Evidence: ${cachedCount} cached, ${evidence.length - cachedCount} collected; ${incompleteCount} incomplete.
+Oldest observation: ${oldestObservation}`
+          );
+        }
+        return sections.join("\n\n");
+      };
       if (findingRows.length === 0 && diagnosticRows.length === 0) {
-        return withSuppressedCount(suppressedCount > 0 ? "No active findings." : "No findings.");
+        return withScanSummary(suppressedCount > 0 ? "No active findings." : "No findings.");
       }
       if (findingRows.length === 0) {
-        return withSuppressedCount(`Diagnostics
+        return withScanSummary(`Diagnostics
 ${renderAsciiTable(diagnosticRows, diagnosticColumns)}`);
       }
       if (diagnosticRows.length === 0) {
-        return withSuppressedCount(renderAsciiTable(findingRows, scanColumns));
+        return withScanSummary(renderAsciiTable(findingRows, scanColumns));
       }
-      return withSuppressedCount(
+      return withScanSummary(
         `${renderAsciiTable(findingRows, scanColumns)}
 
 Diagnostics
@@ -1059,6 +1073,8 @@ var registerConfigCommand = (program) => {
 };
 
 // src/commands/discover.ts
+import { homedir } from "os";
+import { join as join2 } from "path";
 import {
   assertSupportedAwsRegion,
   CloudBurnClient
@@ -1142,6 +1158,19 @@ var validateServiceList = (mode, services) => {
 };
 
 // src/commands/discover.ts
+var parseDiscoveryTimeout = (value) => {
+  const seconds = Number(value);
+  if (!Number.isInteger(seconds) || seconds < 1 || seconds > 2147483) {
+    throw new InvalidArgumentError3("Timeout must be a whole number of seconds between 1 and 2147483.");
+  }
+  return seconds;
+};
+var parseCacheMode = (value) => {
+  if (value === "normal" || value === "refresh" || value === "off") {
+    return value;
+  }
+  throw new InvalidArgumentError3("Cache mode must be normal, refresh, or off.");
+};
 var parseDiscoveryServiceList = (value) => validateServiceList("discovery", parseServiceList(value)) ?? [];
 var describeInitializationMessage = (result) => {
   const baseMessage = result.indexType === "aggregator" ? result.aggregatorAction === "promoted" ? `Promoted the existing local Resource Explorer index in ${result.aggregatorRegion} to the aggregator.` : result.aggregatorAction === "created" ? `Configured ${result.aggregatorRegion} as the Resource Explorer aggregator.` : result.coverage === "full" ? `Resource Explorer aggregator already exists in ${result.aggregatorRegion}.` : `Resource Explorer aggregator already exists in ${result.aggregatorRegion}, but only ${result.observedStatus.indexedRegionCount} of ${result.observedStatus.totalRegionCount} regions are indexed.` : result.status === "EXISTING" ? `Local Resource Explorer setup already exists in ${result.aggregatorRegion}.` : `Local Resource Explorer setup created in ${result.aggregatorRegion}.`;
@@ -1249,7 +1278,10 @@ var registerDiscoverCommand = (program) => {
       "--region <region>",
       "AWS region to discover. Defaults to the current AWS region from AWS_REGION when omitted.",
       parseAwsRegion
-    ).option("--config <path>", "Explicit CloudBurn config file to load (required for config files in CI)").option(
+    ).option("--config <path>", "Explicit CloudBurn config file to load (required for config files in CI)").option("--timeout <seconds>", "Maximum discovery duration in seconds (default: 300).", parseDiscoveryTimeout).option("--cache <mode>", "Evidence cache mode: normal, refresh, or off (default: normal).", parseCacheMode).option(
+      "--cache-dir <path>",
+      "Evidence cache directory (default: $XDG_CACHE_HOME/cloudburn/evidence or ~/.cache/cloudburn/evidence)."
+    ).option("--cache-context <id>", "Effective authorization/session-policy revision for evidence reuse.").option(
       "--enabled-rules <ruleIds>",
       "Comma-separated rule IDs to enable. When set, CloudBurn checks only these rules. By default, AWS Core preset rules are enabled.",
       parseRuleIdList
@@ -1269,6 +1301,11 @@ var registerDiscoverCommand = (program) => {
         const configOverride = toDiscoveryConfigOverride(options);
         const loadedConfig = await scanner.loadConfig(options.config);
         const discoveryOptions = {
+          cache: {
+            mode: options.cache ?? "normal",
+            directory: options.cacheDir ?? join2(process.env.XDG_CACHE_HOME ?? join2(homedir(), ".cache"), "cloudburn", "evidence"),
+            ...options.cacheContext === void 0 ? {} : { authorizationContext: options.cacheContext }
+          },
           target: resolveDiscoveryTarget(options.region)
         };
         if (configOverride !== void 0) {
@@ -1280,6 +1317,9 @@ var registerDiscoverCommand = (program) => {
         if (onProgress !== void 0) {
           discoveryOptions.onProgress = onProgress;
         }
+        if (options.timeout !== void 0) {
+          discoveryOptions.timeoutMs = options.timeout * 1e3;
+        }
         const result = await scanner.discover(discoveryOptions);
         const format = resolveOutputFormat(command, void 0, loadedConfig.discovery.format ?? "table");
         const output = renderResponse({ kind: "scan-result", result }, format);
@@ -1297,6 +1337,7 @@ var registerDiscoverCommand = (program) => {
     [
       "cloudburn discover",
       "cloudburn discover --region eu-central-1",
+      "cloudburn discover --cache refresh",
       "cloudburn discover status",
       "cloudburn discover init"
     ]
@@ -1556,7 +1597,7 @@ var isCliEntrypoint = (moduleUrl, argvEntry = process.argv[1]) => {
 };
 var createProgram = () => {
   const program = createCliCommand();
-  program.name("cloudburn").usage("[command]").description("Know what you spend. Fix what you waste.").version("0.16.0").option("--debug", "Write execution trace messages to stderr").option("--format <format>", OUTPUT_FORMAT_OPTION_DESCRIPTION, parseOutputFormat);
+  program.name("cloudburn").usage("[command]").description("Know what you spend. Fix what you waste.").version("0.17.0").option("--debug", "Write execution trace messages to stderr").option("--format <format>", OUTPUT_FORMAT_OPTION_DESCRIPTION, parseOutputFormat);
   configureCliHelp(program);
   program.exitOverride();
   registerCompletionCommand(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudburn",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Cloudburn CLI for cloud cost optimization",
   "homepage": "https://cloudburn.io/docs",
   "bugs": {
@@ -20,7 +20,7 @@
   ],
   "dependencies": {
     "commander": "^13.1.0",
-    "@cloudburn/sdk": "0.32.0"
+    "@cloudburn/sdk": "0.34.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.3",
@@ -51,6 +51,8 @@
     "build": "tsup",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
+    "test:e2e": "node --test test/e2e/*.test.mjs",
+    "test:package": "node --test test/package/*.test.mjs",
     "lint": "biome check --error-on-warnings .",
     "lint:fix": "biome check --write .",
     "clean": "rm -rf dist",