cloudburn 0.6.2 → 0.7.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,7 +2,460 @@
 
 // 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";
@@ -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)) {
@@ -279,39 +732,38 @@ 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("--exit-code", "Exit with code 1 when findings exist").action(async (options, command) => {
+      await runCommand(async () => {
+        const scanner = new CloudBurnClient();
+        const result = await scanner.discover({ target: resolveDiscoveryTarget(options.region) });
+        const format = resolveOutputFormat(command);
+        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 +781,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 +808,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 +837,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(
         {
@@ -431,14 +883,14 @@ rules:
     severity: error
 `;
 var registerInitCommand = (program) => {
-  program.command("init").description("Print a starter .cloudburn.yml configuration").option("--format <format>", OUTPUT_FORMAT_OPTION_DESCRIPTION, parseOutputFormat).action((options, command) => {
+  program.command("init").description("Print a starter .cloudburn.yml configuration").action(function() {
     const output = renderResponse(
       {
         kind: "document",
         content: starterConfig,
         contentType: "application/yaml"
       },
-      resolveOutputFormat(command, options.format, "text")
+      resolveOutputFormat(this, void 0, "text")
     );
     process.stdout.write(`${output}
 `);
@@ -448,15 +900,15 @@ var registerInitCommand = (program) => {
 // 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}
 `);
@@ -466,39 +918,36 @@ var registerRulesListCommand = (program) => {
 // src/commands/scan.ts
 import { CloudBurnClient as CloudBurnClient2 } from "@cloudburn/sdk";
 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("--exit-code", "Exit with code 1 when findings exist").action(async (path, options, command) => {
+      try {
+        const scanner = new CloudBurnClient2();
+        const result = await scanner.scanStatic(path ?? process.cwd());
+        const format = resolveOutputFormat(command);
+        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.7.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.7.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.11.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.6",