cloudburn 0.6.2 → 0.8.0

package/README.md

@@ -8,6 +8,36 @@ Command-line interface for Cloudburn cloud cost optimization.
 npm install -g cloudburn
 ```
 
+## Shell completion
+
+Inspect the available completion subcommands:
+
+```sh
+cloudburn completion
+cloudburn completion zsh --help
+```
+
+Generate a completion script for your shell and source it directly:
+
+```sh
+source <(cloudburn completion zsh)
+source <(cloudburn completion bash)
+cloudburn completion fish | source
+```
+
+To enable completion persistently, add one of the following lines to your shell config:
+
+```sh
+# ~/.zshrc
+source <(cloudburn completion zsh)
+
+# ~/.bashrc
+source <(cloudburn completion bash)
+
+# ~/.config/fish/config.fish
+cloudburn completion fish | source
+```
+
 ## Usage
 
 ```sh
@@ -23,6 +53,9 @@ cloudburn scan ./template.yaml
 cloudburn scan ./iac
 cloudburn discover
 cloudburn discover --region all
+cloudburn rules
+cloudburn completion
+cloudburn completion zsh
 ```
 
 `cloudburn scan --format json` emits the lean canonical grouped result:

package/dist/cli.js

@@ -2,11 +2,464 @@
 
 // src/cli.ts
 import { pathToFileURL } from "url";
+
+// src/completion/engine.ts
+var buildCompletionTree = (command) => {
+  const help = command.createHelp();
+  return {
+    commands: help.visibleCommands(command).map((childCommand) => buildCompletionTree(childCommand)),
+    name: command.name(),
+    options: collectVisibleOptions([...help.visibleOptions(command), ...help.visibleGlobalOptions(command)])
+  };
+};
+var collectVisibleOptions = (options) => options.map((option) => ({
+  expectsValue: option.required || option.optional,
+  tokens: [option.short, option.long].filter((token) => token !== void 0)
+}));
+var flattenOptionTokens = (options) => {
+  const seen = /* @__PURE__ */ new Set();
+  const tokens = [];
+  for (const option of options) {
+    for (const token of option.tokens) {
+      if (seen.has(token)) {
+        continue;
+      }
+      seen.add(token);
+      tokens.push(token);
+    }
+  }
+  return tokens;
+};
+var findOption = (options, token) => options.find((option) => option.tokens.includes(token));
+var parseOptionToken = (token) => {
+  const separatorIndex = token.indexOf("=");
+  if (separatorIndex === -1) {
+    return { hasInlineValue: false, name: token };
+  }
+  return {
+    hasInlineValue: true,
+    name: token.slice(0, separatorIndex)
+  };
+};
+var createCompletionTree = (command) => buildCompletionTree(command);
+var resolveCompletionSuggestions = (root, words) => {
+  const committedWords = words.length === 0 ? [] : words.slice(0, -1);
+  const partialWord = words.at(-1) ?? "";
+  let currentNode = root;
+  let expectsOptionValue = false;
+  for (const word of committedWords) {
+    if (expectsOptionValue) {
+      expectsOptionValue = false;
+      continue;
+    }
+    if (word.startsWith("-")) {
+      const parsedOption = parseOptionToken(word);
+      const option = findOption(currentNode.options, parsedOption.name);
+      if (option?.expectsValue && !parsedOption.hasInlineValue) {
+        expectsOptionValue = true;
+      }
+      continue;
+    }
+    const nextNode = currentNode.commands.find((command) => command.name === word);
+    if (nextNode !== void 0) {
+      currentNode = nextNode;
+    }
+  }
+  if (expectsOptionValue) {
+    return [];
+  }
+  if (partialWord.startsWith("-")) {
+    const parsedOption = parseOptionToken(partialWord);
+    if (parsedOption.hasInlineValue && findOption(currentNode.options, parsedOption.name) !== void 0) {
+      return [];
+    }
+    return flattenOptionTokens(currentNode.options).filter((token) => token.startsWith(partialWord));
+  }
+  const commandSuggestions = currentNode.commands.map((command) => command.name).filter((commandName) => commandName.startsWith(partialWord));
+  if (partialWord.length > 0) {
+    return commandSuggestions;
+  }
+  return [...commandSuggestions, ...flattenOptionTokens(currentNode.options)];
+};
+
+// src/completion/shell.ts
+var renderZshCompletion = (commandName) => `#compdef ${commandName}
+
+_${commandName}() {
+  local -a suggestions
+  suggestions=("\${(@f)$("\${words[1]}" __complete -- "\${words[@]:1:$((CURRENT - 1))}")}")
+  _describe 'values' suggestions
+}
+
+compdef _${commandName} ${commandName}
+`;
+var renderBashCompletion = (commandName) => `_${commandName}() {
+  local -a args=()
+  local line
+  local -a suggestions=()
+
+  args=("\${COMP_WORDS[@]:1:$COMP_CWORD}")
+  if [ "$COMP_CWORD" -ge "\${#COMP_WORDS[@]}" ]; then
+    args+=("")
+  fi
+
+  while IFS= read -r line; do
+    suggestions+=("$line")
+  done < <("\${COMP_WORDS[0]}" __complete -- "\${args[@]}")
+
+  COMPREPLY=("\${suggestions[@]}")
+}
+
+complete -F _${commandName} ${commandName}
+`;
+var renderFishCompletion = (commandName) => `function __fish_${commandName}_complete
+  set -l words (commandline -opc)
+  if test (count $words) -gt 0
+    set -e words[1]
+  end
+  set -a words (commandline -ct)
+  ${commandName} __complete -- $words
+end
+
+complete -c ${commandName} -f -a "(__fish_${commandName}_complete)"
+`;
+var generateCompletionScript = (shell, program) => {
+  const commandName = program.name();
+  switch (shell) {
+    case "zsh":
+      return renderZshCompletion(commandName);
+    case "bash":
+      return renderBashCompletion(commandName);
+    case "fish":
+      return renderFishCompletion(commandName);
+  }
+};
+
+// src/help.ts
 import { Command } from "commander";
+var ITEM_INDENT = 2;
+var SPACER_WIDTH = 2;
+var INCOMPLETE_HELP_ERROR_CODES = /* @__PURE__ */ new Set([
+  "commander.missingArgument",
+  "commander.missingMandatoryOptionValue",
+  "commander.optionMissingArgument"
+]);
+var buildCommandPath = (command) => {
+  const names = [];
+  let current = command;
+  while (current !== null) {
+    names.unshift(current.name());
+    current = current.parent;
+  }
+  return names.join(" ");
+};
+var visibleCommands = (command) => command.commands.filter((subcommand) => !subcommand._hidden);
+var getCommandExamples = (command) => {
+  const { _cloudburnExamples } = command;
+  return _cloudburnExamples ?? [];
+};
+var getCommandUsageGuidance = (command) => {
+  const { _cloudburnUsageGuidance } = command;
+  return _cloudburnUsageGuidance ?? null;
+};
+var getHelpScenario = (command) => command._cloudburnRenderingHelpScenario ?? "explicit";
+var inferHelpScenario = (errorCode) => errorCode !== void 0 && INCOMPLETE_HELP_ERROR_CODES.has(errorCode) ? "incomplete" : "error";
+var buildSubcommandGuidance = (command) => {
+  const firstSubcommand = visibleCommands(command).at(0);
+  if (firstSubcommand === void 0) {
+    return null;
+  }
+  return `Specify one of the available subcommands to continue.
+Try: ${buildCommandPath(command)} ${firstSubcommand.name()}`;
+};
+var buildExampleGuidance = (command) => {
+  const [firstExample] = getCommandExamples(command);
+  return firstExample === void 0 ? null : `Try: ${firstExample}`;
+};
+var buildRecoveryGuidance = (command, scenario) => {
+  if (scenario !== "incomplete") {
+    return null;
+  }
+  return buildSubcommandGuidance(command) ?? buildExampleGuidance(command);
+};
+var formatDescriptionItem = (term, description, termWidth, helper) => {
+  const itemIndent = " ".repeat(ITEM_INDENT);
+  if (!description.includes("\n")) {
+    return helper.formatItem(term, termWidth, description, helper);
+  }
+  const paddedTerm = term.padEnd(termWidth + term.length - helper.displayWidth(term));
+  const continuationIndent = `${itemIndent}${" ".repeat(termWidth)}${" ".repeat(SPACER_WIDTH)}`;
+  const [firstLine, ...remainingLines] = description.split("\n");
+  return [
+    `${itemIndent}${paddedTerm}${" ".repeat(SPACER_WIDTH)}${firstLine}`,
+    ...remainingLines.map((line) => `${continuationIndent}${line}`)
+  ].join("\n");
+};
+var formatSection = (title, items, termWidth, helper) => {
+  if (items.length === 0) {
+    return [];
+  }
+  return [
+    helper.styleTitle(title),
+    ...items.map(({ description, term }) => formatDescriptionItem(term, description, termWidth, helper)),
+    ""
+  ];
+};
+var formatExamplesSection = (examples) => {
+  if (examples.length === 0) {
+    return [];
+  }
+  return ["Examples:", ...examples.map((example) => `  ${example}`), ""];
+};
+var formatGuidanceBlock = (guidance) => {
+  if (guidance === null) {
+    return [];
+  }
+  return [...guidance.trim().split("\n"), ""];
+};
+var formatCloudBurnHelp = (command, helper) => {
+  const cloudBurnHelp = helper;
+  const helpWidth = helper.helpWidth ?? 80;
+  const scenario = getHelpScenario(command);
+  const localOptions = helper.visibleOptions(command);
+  const globalOptions = helper.visibleGlobalOptions(command);
+  const commands = helper.visibleCommands(command);
+  const examples = getCommandExamples(command);
+  const usageGuidance = getCommandUsageGuidance(command);
+  const recoveryGuidance = buildRecoveryGuidance(command, scenario);
+  const termWidth = Math.max(
+    helper.longestArgumentTermLength(command, helper),
+    helper.longestOptionTermLength(command, helper),
+    helper.longestGlobalOptionTermLength(command, helper),
+    helper.longestSubcommandTermLength(command, helper)
+  );
+  const output = [];
+  const description = helper.commandDescription(command);
+  if (!cloudBurnHelp._cloudburnIsErrorOutput && description.length > 0) {
+    output.push(helper.boxWrap(helper.styleCommandDescription(description), helpWidth), "");
+  }
+  output.push(`${helper.styleTitle("Usage:")} ${helper.styleUsage(helper.commandUsage(command))}`, "");
+  output.push(...formatExamplesSection(examples));
+  output.push(...formatGuidanceBlock(usageGuidance));
+  output.push(
+    ...formatSection(
+      "Available Commands:",
+      commands.map((subcommand) => ({
+        description: helper.styleSubcommandDescription(helper.subcommandDescription(subcommand)),
+        term: helper.styleSubcommandTerm(helper.subcommandTerm(subcommand))
+      })),
+      termWidth,
+      helper
+    )
+  );
+  output.push(
+    ...formatSection(
+      "Arguments:",
+      helper.visibleArguments(command).map((argument) => ({
+        description: helper.styleArgumentDescription(helper.argumentDescription(argument)),
+        term: helper.styleArgumentTerm(helper.argumentTerm(argument))
+      })),
+      termWidth,
+      helper
+    )
+  );
+  output.push(
+    ...formatSection(
+      command.parent === null ? "Global Flags:" : "Flags:",
+      localOptions.map((option) => ({
+        description: helper.styleOptionDescription(helper.optionDescription(option)),
+        term: helper.styleOptionTerm(helper.optionTerm(option))
+      })),
+      termWidth,
+      helper
+    )
+  );
+  if (command.parent !== null) {
+    output.push(
+      ...formatSection(
+        "Global Flags:",
+        globalOptions.map((option) => ({
+          description: helper.styleOptionDescription(helper.optionDescription(option)),
+          term: helper.styleOptionTerm(helper.optionTerm(option))
+        })),
+        termWidth,
+        helper
+      )
+    );
+  }
+  output.push(...formatGuidanceBlock(recoveryGuidance));
+  if (scenario === "error" && commands.length > 0) {
+    output.push(`Use "${buildCommandPath(command)} [command] --help" for more information about a command.`, "");
+  }
+  while (output.at(-1) === "") {
+    output.pop();
+  }
+  return `${output.join("\n")}
+`;
+};
+var prepareCloudBurnHelpContext = function(contextOptions) {
+  this._cloudburnIsErrorOutput = !!contextOptions.error;
+  this.helpWidth = this.helpWidth ?? contextOptions.helpWidth ?? 80;
+};
+var CloudBurnCommand = class _CloudBurnCommand extends Command {
+  _cloudburnExamples;
+  _cloudburnPendingHelpScenario;
+  _cloudburnRenderingHelpScenario;
+  _cloudburnUsageGuidance;
+  /**
+   * Creates CloudBurn subcommands that inherit the scenario-aware help behavior.
+   *
+   * @param name - Optional subcommand name supplied by Commander.
+   * @returns A new CloudBurn-aware command instance.
+   */
+  createCommand(name) {
+    return new _CloudBurnCommand(name);
+  }
+  /**
+   * Captures the error scenario so Commander help-after-error renders the correct layout.
+   *
+   * @param message - Error text emitted by Commander.
+   * @param errorOptions - Commander exit metadata including the error code.
+   * @returns Never returns because Commander exits or throws via exitOverride.
+   */
+  error(message, errorOptions) {
+    this._cloudburnPendingHelpScenario = inferHelpScenario(errorOptions?.code);
+    return super.error(message, errorOptions);
+  }
+  /**
+   * Returns help text using the shared CloudBurn scenario rules.
+   *
+   * @param context - Commander help context.
+   * @returns The formatted help text.
+   */
+  helpInformation(context) {
+    return this.renderWithHelpScenario(context, () => super.helpInformation(context));
+  }
+  renderWithHelpScenario(context, render) {
+    const previousScenario = this._cloudburnRenderingHelpScenario;
+    const pendingScenario = this._cloudburnPendingHelpScenario;
+    this._cloudburnRenderingHelpScenario = context?.error ? pendingScenario ?? "error" : pendingScenario ?? "explicit";
+    this._cloudburnPendingHelpScenario = void 0;
+    try {
+      return render();
+    } finally {
+      this._cloudburnRenderingHelpScenario = previousScenario;
+    }
+  }
+};
+var outputScenarioHelp = (command, scenario) => {
+  const cloudBurnCommand = command;
+  const previousScenario = cloudBurnCommand._cloudburnPendingHelpScenario;
+  cloudBurnCommand._cloudburnPendingHelpScenario = scenario;
+  try {
+    command.outputHelp();
+  } finally {
+    cloudBurnCommand._cloudburnPendingHelpScenario = previousScenario;
+  }
+};
+var createCliCommand = () => new CloudBurnCommand();
+var createHelpConfiguration = () => ({
+  formatHelp: formatCloudBurnHelp,
+  prepareContext: prepareCloudBurnHelpContext,
+  showGlobalOptions: true,
+  visibleCommands
+});
+var configureCliHelp = (program) => {
+  program.configureHelp(createHelpConfiguration());
+  program.showHelpAfterError();
+  program.showSuggestionAfterError();
+};
+var registerParentCommand = (parent, name, description) => parent.command(name).description(description).usage("[command]").allowExcessArguments(true).action(function() {
+  if (this.args.length > 0) {
+    this.unknownCommand();
+    return;
+  }
+  outputScenarioHelp(this, "incomplete");
+});
+var setCommandExamples = (command, examples) => {
+  command._cloudburnExamples = examples;
+  return command;
+};
+var setCommandUsageGuidance = (command, guidance) => {
+  command._cloudburnUsageGuidance = guidance.trim();
+  return command;
+};
+
+// src/commands/completion.ts
+var getRootCommand = (command) => {
+  let currentCommand = command;
+  while (currentCommand.parent !== null) {
+    currentCommand = currentCommand.parent;
+  }
+  return currentCommand;
+};
+var getCompletionHelpText = (shell) => {
+  switch (shell) {
+    case "bash":
+      return `
+To load completions in your current shell session:
+
+  source <(cloudburn completion bash)
+
+To load completions for every new session, add this to your shell config:
+
+  source <(cloudburn completion bash)
+`;
+    case "fish":
+      return `
+To load completions in your current shell session:
+
+  cloudburn completion fish | source
+
+To load completions for every new session, add this to your shell config:
+
+  cloudburn completion fish | source
+`;
+    case "zsh":
+      return `
+If shell completion is not already enabled in your environment you will need
+to enable it. You can execute the following once:
+
+  echo "autoload -U compinit; compinit" >> ~/.zshrc
+
+To load completions in your current shell session:
+
+  source <(cloudburn completion zsh)
+
+To load completions for every new session, add this to your shell config:
+
+  source <(cloudburn completion zsh)
+`;
+  }
+};
+var registerCompletionCommand = (program) => {
+  const completionCommand = registerParentCommand(
+    program,
+    "completion",
+    "Generate shell completion scripts for CloudBurn."
+  );
+  for (const shell of ["bash", "fish", "zsh"]) {
+    setCommandUsageGuidance(
+      completionCommand.command(shell).description(`Generate the autocompletion script for the ${shell} shell.`).option("--no-descriptions", "disable completion descriptions").action(function() {
+        const output = generateCompletionScript(shell, getRootCommand(this));
+        process.stdout.write(output);
+      }),
+      getCompletionHelpText(shell)
+    );
+  }
+  program.command("__complete", { hidden: true }).argument("[words...]").allowUnknownOption().action(function(words) {
+    const suggestions = resolveCompletionSuggestions(createCompletionTree(getRootCommand(this)), words ?? []);
+    if (suggestions.length === 0) {
+      return;
+    }
+    process.stdout.write(`${suggestions.join("\n")}
+`);
+  });
+};
 
 // src/commands/discover.ts
 import { assertValidAwsRegion, CloudBurnClient } from "@cloudburn/sdk";
-import { InvalidArgumentError as InvalidArgumentError2 } from "commander";
+import { InvalidArgumentError as InvalidArgumentError3 } from "commander";
 
 // src/exit-codes.ts
 var EXIT_CODE_OK = 0;
@@ -89,7 +542,7 @@ var scanColumns = [
   { key: "startColumn", header: "StartColumn" },
   { key: "message", header: "Message" }
 ];
-var formatOptionDescription = "Output format. table: human-readable terminal output. text: tab-delimited output for grep, sed, and awk. json: machine-readable output for automation and downstream systems.";
+var formatOptionDescription = "Options: table: human-readable terminal output.\ntext: tab-delimited output for grep, sed, and awk.\njson: machine-readable output for automation and downstream systems.";
 var OUTPUT_FORMAT_OPTION_DESCRIPTION = formatOptionDescription;
 var parseOutputFormat = (value) => {
   if (supportedOutputFormats.includes(value)) {
@@ -254,12 +707,22 @@ var renderAsciiTable = (rows, columns) => {
   return [border, header, border, ...body, border].join("\n");
 };
 
+// src/commands/config-options.ts
+import { InvalidArgumentError as InvalidArgumentError2 } from "commander";
+var parseRuleIdList = (value) => {
+  const ruleIds = value.split(",").map((ruleId) => ruleId.trim()).filter((ruleId) => ruleId.length > 0);
+  if (ruleIds.length === 0) {
+    throw new InvalidArgumentError2("Provide at least one rule ID.");
+  }
+  return ruleIds;
+};
+
 // src/commands/discover.ts
 var parseAwsRegion = (value) => {
   try {
     return assertValidAwsRegion(value);
   } catch (err) {
-    throw new InvalidArgumentError2(err instanceof Error ? err.message : "Invalid AWS region.");
+    throw new InvalidArgumentError3(err instanceof Error ? err.message : "Invalid AWS region.");
   }
 };
 var parseDiscoverRegion = (value) => {
@@ -269,6 +732,17 @@ var parseDiscoverRegion = (value) => {
   return parseAwsRegion(value);
 };
 var resolveDiscoveryTarget = (region) => region === void 0 ? { mode: "current" } : region === "all" ? { mode: "all" } : { mode: "region", region };
+var toDiscoveryConfigOverride = (options) => {
+  if (options.enabledRules === void 0 && options.disabledRules === void 0) {
+    return void 0;
+  }
+  return {
+    discovery: {
+      disabledRules: options.disabledRules,
+      enabledRules: options.enabledRules
+    }
+  };
+};
 var runCommand = async (action) => {
   try {
     process.exitCode = await action() ?? EXIT_CODE_OK;
@@ -279,39 +753,49 @@ var runCommand = async (action) => {
   }
 };
 var registerDiscoverCommand = (program) => {
-  const discoverCommand = program.command("discover").description("Run a live AWS discovery").enablePositionalOptions().option(
-    "--region <region>",
-    'Discovery region to use. Pass "all" to require an aggregator index.',
-    parseDiscoverRegion
-  ).option("--format <format>", OUTPUT_FORMAT_OPTION_DESCRIPTION, parseOutputFormat).option("--exit-code", "Exit with code 1 when findings exist").addHelpText(
-    "after",
-    `
-Examples:
-  cloudburn discover
-  cloudburn discover --region eu-central-1
-  cloudburn discover --region all
-  cloudburn discover list-enabled-regions
-  cloudburn discover init
-`
-  ).action(async (options, command) => {
-    await runCommand(async () => {
-      const scanner = new CloudBurnClient();
-      const result = await scanner.discover({ target: resolveDiscoveryTarget(options.region) });
-      const format = resolveOutputFormat(command, options.format);
-      const output = renderResponse({ kind: "scan-result", result }, format);
-      process.stdout.write(`${output}
+  const discoverCommand = setCommandExamples(
+    program.command("discover").description("Run a live AWS discovery").enablePositionalOptions().option(
+      "--region <region>",
+      'Discovery region to use. Pass "all" to require an aggregator index.',
+      parseDiscoverRegion
+    ).option("--config <path>", "Explicit CloudBurn config file to load").option("--enabled-rules <ruleIds>", "Comma-separated rule IDs to enable", parseRuleIdList).option("--disabled-rules <ruleIds>", "Comma-separated rule IDs to disable", parseRuleIdList).option("--exit-code", "Exit with code 1 when findings exist").action(async (options, command) => {
+      await runCommand(async () => {
+        const scanner = new CloudBurnClient();
+        const loadedConfig = await scanner.loadConfig(options.config);
+        const discoveryOptions = {
+          target: resolveDiscoveryTarget(options.region)
+        };
+        const configOverride = toDiscoveryConfigOverride(options);
+        if (configOverride !== void 0) {
+          discoveryOptions.config = configOverride;
+        }
+        if (options.config !== void 0) {
+          discoveryOptions.configPath = options.config;
+        }
+        const result = await scanner.discover(discoveryOptions);
+        const format = resolveOutputFormat(command, void 0, loadedConfig.discovery.format ?? "table");
+        const output = renderResponse({ kind: "scan-result", result }, format);
+        process.stdout.write(`${output}
 `);
-      if (options.exitCode && countScanResultFindings(result) > 0) {
-        return EXIT_CODE_POLICY_VIOLATION;
-      }
-      return EXIT_CODE_OK;
-    });
-  });
-  discoverCommand.command("list-enabled-regions").description("List AWS regions with a local or aggregator Resource Explorer index").option("--format <format>", OUTPUT_FORMAT_OPTION_DESCRIPTION, parseOutputFormat).action(async (options, command) => {
+        if (options.exitCode && countScanResultFindings(result) > 0) {
+          return EXIT_CODE_POLICY_VIOLATION;
+        }
+        return EXIT_CODE_OK;
+      });
+    }),
+    [
+      "cloudburn discover",
+      "cloudburn discover --region eu-central-1",
+      "cloudburn discover --region all",
+      "cloudburn discover list-enabled-regions",
+      "cloudburn discover init"
+    ]
+  );
+  discoverCommand.command("list-enabled-regions").description("List AWS regions with a local or aggregator Resource Explorer index").action(async (_options, command) => {
     await runCommand(async () => {
       const scanner = new CloudBurnClient();
       const regions = await scanner.listEnabledDiscoveryRegions();
-      const format = resolveOutputFormat(command, options.format);
+      const format = resolveOutputFormat(command);
       const output = renderResponse(
         {
           kind: "record-list",
@@ -329,14 +813,14 @@ Examples:
       return EXIT_CODE_OK;
     });
   });
-  discoverCommand.command("init").description("Set up AWS Resource Explorer for CloudBurn").option("--format <format>", OUTPUT_FORMAT_OPTION_DESCRIPTION, parseOutputFormat).option("--region <region>", "Aggregator region to create or reuse during setup", parseAwsRegion).action(async (options, command) => {
+  discoverCommand.command("init").description("Set up AWS Resource Explorer for CloudBurn").option("--region <region>", "Aggregator region to create or reuse during setup", parseAwsRegion).action(async (options, command) => {
     await runCommand(async () => {
       const scanner = new CloudBurnClient();
       const parentRegion = discoverCommand.opts().region;
       const region = options.region ?? (parentRegion === "all" ? void 0 : parentRegion);
       const result = await scanner.initializeDiscovery({ region });
       const message = result.status === "EXISTING" ? `Resource Explorer setup already exists in ${result.aggregatorRegion}.` : `Resource Explorer setup created in ${result.aggregatorRegion}.`;
-      const format = resolveOutputFormat(command, options.format);
+      const format = resolveOutputFormat(command);
       const output = renderResponse(
         {
           kind: "status",
@@ -356,11 +840,11 @@ Examples:
       return EXIT_CODE_OK;
     });
   });
-  discoverCommand.command("supported-resource-types").description("List Resource Explorer supported AWS resource types").option("--format <format>", OUTPUT_FORMAT_OPTION_DESCRIPTION, parseOutputFormat).action(async (options, command) => {
+  discoverCommand.command("supported-resource-types").description("List Resource Explorer supported AWS resource types").action(async (_options, command) => {
     await runCommand(async () => {
       const scanner = new CloudBurnClient();
       const resourceTypes = await scanner.listSupportedDiscoveryResourceTypes();
-      const format = resolveOutputFormat(command, options.format);
+      const format = resolveOutputFormat(command);
       const output = renderResponse(
         {
           kind: "record-list",
@@ -385,8 +869,8 @@ Examples:
 
 // src/commands/estimate.ts
 var registerEstimateCommand = (program) => {
-  program.command("estimate").description("Request optional pricing estimates from a self-hosted dashboard").option("--format <format>", OUTPUT_FORMAT_OPTION_DESCRIPTION, parseOutputFormat).option("--server <url>", "Dashboard API base URL").action((options, command) => {
-    const format = resolveOutputFormat(command, options.format);
+  program.command("estimate").description("Request optional pricing estimates from a self-hosted dashboard").option("--server <url>", "Dashboard API base URL").action((options, command) => {
+    const format = resolveOutputFormat(command);
     if (!options.server) {
       const output2 = renderResponse(
         {
@@ -422,41 +906,120 @@ var registerEstimateCommand = (program) => {
 };
 
 // src/commands/init.ts
-var starterConfig = `version: 1
-profile: dev
+import { access, writeFile } from "fs/promises";
+import { dirname, join, resolve } from "path";
+var CONFIG_FILENAMES = [".cloudburn.yml", ".cloudburn.yaml"];
+var starterConfig = `# Static IaC scan configuration.
+# enabled-rules restricts scans to only the listed rule IDs.
+# disabled-rules removes specific rule IDs from the active set.
+# format sets the default output format when --format is not passed.
+iac:
+  enabled-rules:
+    - CLDBRN-AWS-EBS-1
+  disabled-rules:
+    - CLDBRN-AWS-EC2-2
+  format: table
 
-# Profiles are parsed but not applied yet, so configure the active rules block directly for now.
-rules:
-  ec2-instance-type-preferred:
-    severity: error
+# Live AWS discovery configuration.
+# Use the same rule controls here to tune discover runs separately from IaC scans.
+discovery:
+  enabled-rules:
+    - CLDBRN-AWS-EBS-1
+  disabled-rules:
+    - CLDBRN-AWS-S3-1
+  format: json
 `;
+var renderStarterConfig = (command) => renderResponse(
+  {
+    kind: "document",
+    content: starterConfig,
+    contentType: "application/yaml"
+  },
+  resolveOutputFormat(command, void 0, "text")
+);
+var fileExists = async (path) => {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+};
+var findProjectRoot = async (startDirectory) => {
+  let currentDirectory = resolve(startDirectory);
+  while (true) {
+    if (await fileExists(join(currentDirectory, ".git"))) {
+      return currentDirectory;
+    }
+    const parentDirectory = dirname(currentDirectory);
+    if (parentDirectory === currentDirectory) {
+      return resolve(startDirectory);
+    }
+    currentDirectory = parentDirectory;
+  }
+};
 var registerInitCommand = (program) => {
-  program.command("init").description("Print a starter .cloudburn.yml configuration").option("--format <format>", OUTPUT_FORMAT_OPTION_DESCRIPTION, parseOutputFormat).action((options, command) => {
-    const output = renderResponse(
-      {
-        kind: "document",
-        content: starterConfig,
-        contentType: "application/yaml"
-      },
-      resolveOutputFormat(command, options.format, "text")
-    );
-    process.stdout.write(`${output}
+  const initCommand = program.command("init").description("Initialize CloudBurn scaffolding").usage("[command]").action(function() {
+    process.stdout.write(`${renderStarterConfig(this)}
+`);
+    process.exitCode = EXIT_CODE_OK;
+  });
+  initCommand.command("config").description("Create a starter .cloudburn.yml configuration").option("--print", "Print the starter config instead of writing the file").action(async function(options) {
+    try {
+      if (options.print) {
+        process.stdout.write(`${renderStarterConfig(this)}
+`);
+        process.exitCode = EXIT_CODE_OK;
+        return;
+      }
+      const rootDirectory = await findProjectRoot(process.cwd());
+      const existingConfigPath = (await Promise.all(
+        CONFIG_FILENAMES.map(async (filename) => {
+          const path = join(rootDirectory, filename);
+          return await fileExists(path) ? path : void 0;
+        })
+      )).find((path) => path !== void 0);
+      if (existingConfigPath) {
+        throw new Error(
+          `CloudBurn config already exists at ${existingConfigPath}. Use --print to inspect the template.`
+        );
+      }
+      const configPath = join(rootDirectory, ".cloudburn.yml");
+      await writeFile(configPath, starterConfig, { encoding: "utf8", flag: "wx" });
+      const output = renderResponse(
+        {
+          kind: "status",
+          data: {
+            message: "Created CloudBurn config.",
+            path: configPath
+          },
+          text: `Created ${configPath}.`
+        },
+        resolveOutputFormat(this)
+      );
+      process.stdout.write(`${output}
+`);
+      process.exitCode = EXIT_CODE_OK;
+    } catch (err) {
+      process.stderr.write(`${formatError(err)}
 `);
+      process.exitCode = EXIT_CODE_RUNTIME_ERROR;
+    }
   });
 };
 
 // src/commands/rules-list.ts
 import { builtInRuleMetadata } from "@cloudburn/sdk";
 var registerRulesListCommand = (program) => {
-  const rulesCommand = program.command("rules").description("Inspect built-in CloudBurn rules");
-  rulesCommand.command("list").description("List built-in CloudBurn rules").option("--format <format>", OUTPUT_FORMAT_OPTION_DESCRIPTION, parseOutputFormat).action((options, command) => {
+  const rulesCommand = registerParentCommand(program, "rules", "Inspect built-in CloudBurn rules");
+  rulesCommand.command("list").description("List built-in CloudBurn rules").action(function() {
     const output = renderResponse(
       {
         kind: "rule-list",
         emptyMessage: "No built-in rules are available.",
         rules: builtInRuleMetadata
       },
-      resolveOutputFormat(command, options.format, "text")
+      resolveOutputFormat(this, void 0, "text")
     );
     process.stdout.write(`${output}
 `);
@@ -465,40 +1028,51 @@ var registerRulesListCommand = (program) => {
 
 // src/commands/scan.ts
 import { CloudBurnClient as CloudBurnClient2 } from "@cloudburn/sdk";
+var toScanConfigOverride = (options) => {
+  if (options.enabledRules === void 0 && options.disabledRules === void 0) {
+    return void 0;
+  }
+  return {
+    iac: {
+      disabledRules: options.disabledRules,
+      enabledRules: options.enabledRules
+    }
+  };
+};
 var registerScanCommand = (program) => {
-  program.command("scan").description("Run an autodetected static IaC scan").argument("[path]", "Terraform file, CloudFormation template, or directory to scan").option("--format <format>", OUTPUT_FORMAT_OPTION_DESCRIPTION, parseOutputFormat).option("--exit-code", "Exit with code 1 when findings exist").addHelpText(
-    "after",
-    `
-Examples:
-  cloudburn scan ./main.tf
-  cloudburn scan ./template.yaml
-  cloudburn scan ./iac
-`
-  ).action(async (path, options, command) => {
-    try {
-      const scanner = new CloudBurnClient2();
-      const result = await scanner.scanStatic(path ?? process.cwd());
-      const format = resolveOutputFormat(command, options.format);
-      const output = renderResponse({ kind: "scan-result", result }, format);
-      process.stdout.write(`${output}
+  setCommandExamples(
+    program.command("scan").description("Run an autodetected static IaC scan").argument("[path]", "Terraform file, CloudFormation template, or directory to scan").option("--config <path>", "Explicit CloudBurn config file to load").option("--enabled-rules <ruleIds>", "Comma-separated rule IDs to enable", parseRuleIdList).option("--disabled-rules <ruleIds>", "Comma-separated rule IDs to disable", parseRuleIdList).option("--exit-code", "Exit with code 1 when findings exist").action(async (path, options, command) => {
+      try {
+        const scanner = new CloudBurnClient2();
+        const loadedConfig = await scanner.loadConfig(options.config);
+        const configOverride = toScanConfigOverride(options);
+        const scanPath = path ?? process.cwd();
+        const result = configOverride === void 0 && options.config === void 0 ? await scanner.scanStatic(scanPath) : options.config === void 0 ? await scanner.scanStatic(scanPath, configOverride) : await scanner.scanStatic(scanPath, configOverride, { configPath: options.config });
+        const format = resolveOutputFormat(command, void 0, loadedConfig.iac.format ?? "table");
+        const output = renderResponse({ kind: "scan-result", result }, format);
+        process.stdout.write(`${output}
 `);
-      if (options.exitCode && countScanResultFindings(result) > 0) {
-        process.exitCode = EXIT_CODE_POLICY_VIOLATION;
-        return;
-      }
-      process.exitCode = EXIT_CODE_OK;
-    } catch (err) {
-      process.stderr.write(`${formatError(err)}
+        if (options.exitCode && countScanResultFindings(result) > 0) {
+          process.exitCode = EXIT_CODE_POLICY_VIOLATION;
+          return;
+        }
+        process.exitCode = EXIT_CODE_OK;
+      } catch (err) {
+        process.stderr.write(`${formatError(err)}
 `);
-      process.exitCode = EXIT_CODE_RUNTIME_ERROR;
-    }
-  });
+        process.exitCode = EXIT_CODE_RUNTIME_ERROR;
+      }
+    }),
+    ["cloudburn scan ./main.tf", "cloudburn scan ./template.yaml", "cloudburn scan ./iac"]
+  );
 };
 
 // src/cli.ts
 var createProgram = () => {
-  const program = new Command();
-  program.name("cloudburn").description("Know what you spend. Fix what you waste.").version("0.6.2").option("--format <format>", OUTPUT_FORMAT_OPTION_DESCRIPTION, parseOutputFormat);
+  const program = createCliCommand();
+  program.name("cloudburn").usage("[command]").description("Know what you spend. Fix what you waste.").version("0.8.0").option("--format <format>", OUTPUT_FORMAT_OPTION_DESCRIPTION, parseOutputFormat);
+  configureCliHelp(program);
+  registerCompletionCommand(program);
   registerDiscoverCommand(program);
   registerScanCommand(program);
   registerInitCommand(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudburn",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "description": "Cloudburn CLI for cloud cost optimization",
   "type": "module",
   "bin": {
@@ -11,7 +11,7 @@
   ],
   "dependencies": {
     "commander": "^13.1.0",
-    "@cloudburn/sdk": "0.10.0"
+    "@cloudburn/sdk": "0.12.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.6",