@stacksjs/buddy 0.70.88 → 0.70.91

package/dist/commands/cloud.js

@@ -0,0 +1,503 @@
+import process from "node:process";
+import { intro, italic, log, onUnknownSubcommand, outro, prompts, runCommand, underline } from "@stacksjs/cli";
+import {
+  addJumpBox,
+  deleteCdkRemnants,
+  deleteIamUsers,
+  deleteJumpBox,
+  deleteLogGroups,
+  deleteParameterStore,
+  deleteStacksBuckets,
+  deleteStacksFunctions,
+  deleteSubnets,
+  deleteVpcs,
+  getCloudFrontDistributionId,
+  getJumpBoxInstanceId
+} from "@stacksjs/cloud";
+import { path as p } from "@stacksjs/path";
+import { ExitCode } from "@stacksjs/types";
+async function createTemporaryCdkRole(roleName) {
+  const { AWSClient } = await import("@stacksjs/ts-cloud"), client = new AWSClient, trustPolicy = {
+    Version: "2012-10-17",
+    Statement: [
+      {
+        Effect: "Allow",
+        Principal: {
+          Service: "cloudformation.amazonaws.com"
+        },
+        Action: "sts:AssumeRole"
+      }
+    ]
+  };
+  try {
+    try {
+      const getRoleParams = new URLSearchParams({
+        Action: "GetRole",
+        RoleName: roleName,
+        Version: "2010-05-08"
+      });
+      await client.request({
+        service: "iam",
+        region: "us-east-1",
+        method: "POST",
+        path: "/",
+        body: getRoleParams.toString()
+      });
+      log.debug(`Role ${roleName} already exists`);
+      return;
+    } catch (e) {
+      if (!e.message?.includes("NoSuchEntity") && !e.message?.includes("cannot be found"))
+        throw e;
+    }
+    log.info("Creating temporary IAM role to enable stack deletion...");
+    const createRoleParams = new URLSearchParams({
+      Action: "CreateRole",
+      RoleName: roleName,
+      AssumeRolePolicyDocument: JSON.stringify(trustPolicy),
+      Description: "Temporary role to allow CloudFormation to delete stuck stack",
+      Version: "2010-05-08"
+    });
+    await client.request({
+      service: "iam",
+      region: "us-east-1",
+      method: "POST",
+      path: "/",
+      body: createRoleParams.toString()
+    });
+    log.success("Created IAM role");
+    log.info("Attaching permissions...");
+    const attachPolicyParams = new URLSearchParams({
+      Action: "AttachRolePolicy",
+      RoleName: roleName,
+      PolicyArn: "arn:aws:iam::aws:policy/AdministratorAccess",
+      Version: "2010-05-08"
+    });
+    await client.request({
+      service: "iam",
+      region: "us-east-1",
+      method: "POST",
+      path: "/",
+      body: attachPolicyParams.toString()
+    });
+    log.success("IAM role ready for stack deletion");
+    log.info("Waiting for IAM role to propagate...");
+    await new Promise((resolve) => setTimeout(resolve, 1e4));
+  } catch (error) {
+    if (error.message?.includes("EntityAlreadyExists"))
+      log.debug("Role already exists");
+    else
+      throw error;
+  }
+}
+async function deleteTemporaryCdkRole(roleName) {
+  const { AWSClient } = await import("@stacksjs/ts-cloud"), client = new AWSClient;
+  try {
+    const detachPolicyParams = new URLSearchParams({
+      Action: "DetachRolePolicy",
+      RoleName: roleName,
+      PolicyArn: "arn:aws:iam::aws:policy/AdministratorAccess",
+      Version: "2010-05-08"
+    });
+    await client.request({
+      service: "iam",
+      region: "us-east-1",
+      method: "POST",
+      path: "/",
+      body: detachPolicyParams.toString()
+    });
+    const deleteRoleParams = new URLSearchParams({
+      Action: "DeleteRole",
+      RoleName: roleName,
+      Version: "2010-05-08"
+    });
+    await client.request({
+      service: "iam",
+      region: "us-east-1",
+      method: "POST",
+      path: "/",
+      body: deleteRoleParams.toString()
+    });
+    log.success("Cleaned up temporary IAM role");
+  } catch (error) {
+    log.debug(`Could not clean up temporary role: ${error.message}`);
+  }
+}
+function isResultError(result) {
+  if (!result || typeof result !== "object")
+    return !1;
+  const r = result;
+  if (typeof r.isErr === "function")
+    return r.isErr();
+  return !!r.isErr;
+}
+function getResultError(result) {
+  if (!result || typeof result !== "object")
+    return "Unknown error";
+  return String(result.error || "Unknown error");
+}
+function getResultValue(result) {
+  if (!result || typeof result !== "object")
+    return;
+  return result.value;
+}
+export function cloud(buddy) {
+  const descriptions = {
+    cloud: "Interact with the Stacks Cloud",
+    ssh: "SSH into the Stacks Cloud",
+    add: "Add a resource to the Stacks Cloud",
+    remove: "Remove the Stacks Cloud. In case it fails, try again",
+    optimizeCost: "Remove certain resources that may be re-applied at a later time",
+    cleanUp: "Remove all resources that were retained during the cloud deletion",
+    invalidateCache: "Invalidate the CloudFront cache",
+    diff: "Show the diff of the current, undeployed cloud changes ",
+    dashboard: "Run the local Stacks Cloud management cockpit (servers, sites, deploys)",
+    host: "Host to bind the dashboard to",
+    port: "Port to bind the dashboard to",
+    env: "Environment to manage",
+    paths: "The paths to invalidate",
+    project: "Target a specific project",
+    verbose: "Enable verbose output"
+  };
+  buddy.command("cloud", descriptions.cloud).option("--ssh", descriptions.ssh, { default: !1 }).option("--connect", descriptions.ssh, { default: !1 }).option("--invalidate-cache", descriptions.invalidateCache, { default: !1 }).option("--paths [paths]", descriptions.paths).option("--diff", descriptions.diff, { default: !1 }).option("-p, --project [project]", descriptions.project, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (options) => {
+    log.debug("Running `buddy cloud` ...", options);
+    const startTime = performance.now();
+    if (options.ssh || options.connect) {
+      const jumpBoxId = await getJumpBoxInstanceId(), result = await runCommand(`aws ssm start-session --target ${jumpBoxId}`, {
+        ...options,
+        cwd: p.projectPath(),
+        stdin: "pipe"
+      });
+      if (isResultError(result)) {
+        await outro("While running the cloud command, there was an issue", { startTime, useSeconds: !0 }, getResultError(result));
+        process.exit(ExitCode.FatalError);
+      }
+      await outro("Exited", { startTime, useSeconds: !0 });
+      process.exit(ExitCode.Success);
+    }
+    if (options.invalidateCache) {
+      const { confirm } = await prompts({
+        name: "confirm",
+        type: "confirm",
+        message: "Would you like to invalidate the CDN (CloudFront) cache?"
+      });
+      if (!confirm) {
+        await outro("Exited", { startTime, useSeconds: !0 });
+        process.exit(ExitCode.Success);
+      }
+      log.info("Invalidating the CloudFront cache...");
+      const { AWSCloudFrontClient } = await import("@stacksjs/ts-cloud"), cloudfront = new AWSCloudFrontClient, distributionId = await getCloudFrontDistributionId();
+      try {
+        const invalidationId = await cloudfront.invalidateAll(distributionId);
+        log.success(`Invalidation created: ${invalidationId}`);
+        log.info("Status: pending");
+      } catch (err) {
+        log.error(`Failed to invalidate CloudFront cache: ${err.message}`);
+      }
+      await outro("Exited", { startTime, useSeconds: !0 });
+      process.exit(ExitCode.Success);
+    }
+    if (options.diff) {
+      try {
+        const { InfrastructureGenerator } = await import("@stacksjs/ts-cloud"), { CloudFormationClient } = await import("@stacksjs/ts-cloud/aws"), { tsCloud: cloudConfig } = await import("~/config/cloud"), environment = process.env.APP_ENV || process.env.NODE_ENV || "production", newTemplate = new InfrastructureGenerator({
+          config: cloudConfig,
+          environment
+        }).generate().toJSON(), stackName = `${cloudConfig.project?.slug || "stacks"}-${environment}`, cfn = new CloudFormationClient(process.env.AWS_REGION || "us-east-1");
+        let currentTemplate = "{}";
+        try {
+          currentTemplate = (await cfn.getTemplate(stackName)).TemplateBody;
+        } catch {
+          log.info("No deployed stack found. Showing full template as diff.");
+        }
+        if (currentTemplate === newTemplate)
+          log.info("No changes detected.");
+        else {
+          log.info("Changes detected between deployed and local template:");
+          log.info(`Current template: ${currentTemplate.length} bytes`);
+          log.info(`New template: ${newTemplate.length} bytes`);
+        }
+      } catch (error) {
+        log.error(`Failed to compute diff: ${error.message}`);
+      }
+      await outro("Cloud diff complete", { startTime, useSeconds: !0 });
+      process.exit(ExitCode.Success);
+    }
+    log.info("Not implemented yet. Read more about `buddy cloud` here: https://stacksjs.com/docs/cloud");
+    process.exit(ExitCode.Success);
+  });
+  buddy.command("cloud:add", descriptions.add).option("--jump-box", "Remove the jump-box", { default: !1 }).option("-p, --project [project]", descriptions.project, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (options) => {
+    log.debug("Running `buddy cloud:add` ...", options);
+    const startTime = await intro("buddy cloud:add");
+    if (options.jumpBox) {
+      const { confirm } = await prompts({
+        name: "confirm",
+        type: "confirm",
+        message: "Would you like to add a jump-box to your cloud?"
+      });
+      if (!confirm) {
+        await outro("Exited", { startTime, useSeconds: !0 });
+        process.exit(ExitCode.Success);
+      }
+      log.info("The jump-box is getting added to your cloud resources...");
+      log.info("This takes a few moments, please be patient.");
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+      const result = await addJumpBox();
+      if (isResultError(result)) {
+        await outro("While running the cloud:add command, there was an issue", { startTime, useSeconds: !0 }, getResultError(result));
+        process.exit(ExitCode.FatalError);
+      }
+      log.info(italic("View the jump-box in the AWS console:"));
+      log.info(underline("https://us-east-1.console.aws.amazon.com/ec2/home?region=us-east-1#Instances:instanceState=running"));
+      log.info(italic("Once it finished initializing, you may SSH into it:"));
+      log.info(underline("buddy cloud --ssh"));
+      await outro("Your jump-box was added.", {
+        startTime,
+        useSeconds: !0
+      });
+      process.exit(ExitCode.Success);
+    }
+    log.info("This functionality is not yet implemented.");
+    process.exit(ExitCode.Success);
+  });
+  buddy.command("cloud:remove", descriptions.remove).alias("cloud:destroy").alias("cloud:rm").alias("undeploy").option("--jump-box", "Remove the jump-box", { default: !1 }).option("--force", "Force deletion of stack in bad state", { default: !1 }).option("--yes", "Skip confirmation prompts", { default: !1 }).option("-p, --project [project]", descriptions.project, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (options) => {
+    log.debug("Running `buddy cloud:remove` ...", options);
+    const startTime = await intro("buddy cloud:remove");
+    if (options.jumpBox) {
+      const { confirm } = await prompts({
+        name: "confirm",
+        type: "confirm",
+        message: "Would you like to remove your jump-box for now?"
+      });
+      if (!confirm) {
+        await outro("Exited", { startTime, useSeconds: !0 });
+        process.exit(ExitCode.Success);
+      }
+      const result = await deleteJumpBox();
+      if (isResultError(result)) {
+        await outro("While removing your jump-box, there was an issue", { startTime, useSeconds: !0 }, getResultError(result));
+        process.exit(ExitCode.FatalError);
+      }
+      await outro("Your jump-box was removed.", {
+        startTime,
+        useSeconds: !0
+      });
+      process.exit(ExitCode.Success);
+    }
+    console.log("");
+    console.log("Removing cloud infrastructure...");
+    console.log(`   ${italic("This typically takes 2-5 minutes.")}`);
+    console.log("");
+    const environment = process.env.APP_ENV || process.env.NODE_ENV || "production";
+    if (!process.env.AWS_ACCESS_KEY_ID || !process.env.AWS_SECRET_ACCESS_KEY) {
+      const { existsSync, readFileSync } = await import("node:fs"), { projectPath } = await import("@stacksjs/path"), envFiles = [
+        projectPath(`.env.${environment}`),
+        projectPath(".env")
+      ];
+      for (const envPath of envFiles)
+        if (existsSync(envPath)) {
+          const lines = readFileSync(envPath, "utf-8").split(`
+`);
+          for (const line of lines) {
+            const trimmed = line.trim();
+            if (trimmed.startsWith("#") || !trimmed.includes("="))
+              continue;
+            const [key, ...valueParts] = trimmed.split("="), value = valueParts.join("=").replace(/^["']|["']$/g, "");
+            if (key === "AWS_ACCESS_KEY_ID" || key === "AWS_SECRET_ACCESS_KEY" || key === "AWS_REGION" || key === "AWS_ACCOUNT_ID")
+              process.env[key] = value;
+          }
+          break;
+        }
+    }
+    delete process.env.AWS_PROFILE;
+    try {
+      const { undeployStack } = await import("../../../actions/deploy"), region = process.env.AWS_REGION || "us-east-1";
+      await undeployStack({
+        environment,
+        region,
+        verbose: options.verbose
+      });
+      await outro("Cloud infrastructure removed", { startTime, useSeconds: !0 });
+      process.exit(ExitCode.Success);
+    } catch (error) {
+      console.log("");
+      console.error("\u2717 Failed to remove cloud infrastructure");
+      const errorStr = String(error.message || error);
+      if (errorStr.includes("security token") || errorStr.includes("credentials")) {
+        console.log("");
+        console.error("  AWS credentials are invalid or expired");
+        console.log("  Check your AWS credentials in .env.production:");
+        console.log("    - AWS_ACCESS_KEY_ID");
+        console.log("    - AWS_SECRET_ACCESS_KEY");
+      } else if (errorStr.includes("region") || errorStr.includes("AWS_REGION")) {
+        console.log("");
+        console.error("  AWS Region not configured");
+        console.log("  Add AWS_REGION to your .env.production file");
+      } else if (errorStr.includes("AccessDenied")) {
+        console.log("");
+        console.error("  Access denied");
+        console.log("  Your AWS credentials may not have permission to delete stacks");
+      } else
+        console.error(`  ${errorStr}`);
+      console.log("");
+      console.log("Troubleshooting:");
+      console.log("  ./buddy cloud:cleanup   - Clean up resources manually");
+      console.log("  --verbose               - Show detailed error information");
+      console.log("");
+      if (options.verbose)
+        console.error("Error details:", error);
+      await outro("Failed to remove infrastructure", { startTime, useSeconds: !0 });
+      process.exit(ExitCode.FatalError);
+    }
+  });
+  buddy.command("cloud:optimize-cost", descriptions.optimizeCost).option("--jump-box", "Remove the jump-box", { default: !0 }).option("-p, --project [project]", descriptions.project, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (options) => {
+    log.debug("Running `buddy cloud:optimize-cost` ...", options);
+    const startTime = await intro("buddy cloud:optimize-cost");
+    if (options.jumpBox) {
+      const { confirm } = await prompts({
+        name: "confirm",
+        type: "confirm",
+        message: "Would you like to remove your jump-box to optimize your costs?"
+      });
+      if (!confirm) {
+        await outro("Exited", { startTime, useSeconds: !0 });
+        process.exit(ExitCode.Success);
+      }
+      await deleteJumpBox();
+      await outro("Your jump-box was removed & cost optimizations are applied.", { startTime, useSeconds: !0 });
+      process.exit(ExitCode.Success);
+    }
+    await outro("No cost optimization was applied", {
+      startTime,
+      useSeconds: !0
+    });
+    process.exit(ExitCode.Success);
+  });
+  buddy.command("cloud:cleanup", descriptions.cleanUp).alias("cloud:clean-up").option("-p, --project [project]", descriptions.project, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (options) => {
+    log.debug("Running `buddy cloud:cleanup` ...", options);
+    const startTime = await intro("buddy cloud:cleanup");
+    delete process.env.AWS_PROFILE;
+    log.info("Cleaning up your cloud resources will take a while to complete. Please be patient.");
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+    const cleanupSteps = [
+      { label: "jump-boxes", fn: deleteJumpBox, ignoreErrors: ["Jump-box not found"] },
+      { label: "retained S3 buckets", fn: deleteStacksBuckets },
+      { label: "retained Lambda functions", fn: deleteStacksFunctions, ignoreErrors: ["No stacks functions found"] },
+      { label: "remaining Stacks logs", fn: deleteLogGroups },
+      { label: "stored parameters", fn: deleteParameterStore },
+      { label: "VPCs", fn: deleteVpcs },
+      { label: "Subnets", fn: deleteSubnets },
+      { label: "CDK remnants", fn: deleteCdkRemnants },
+      { label: "IAM users", fn: deleteIamUsers }
+    ], errors = [];
+    for (const step of cleanupSteps) {
+      log.info(`Removing any ${step.label}...`);
+      try {
+        const result = await step.fn();
+        if (isResultError(result)) {
+          const errMsg = getResultError(result);
+          if (!step.ignoreErrors?.includes(errMsg)) {
+            log.warn(`${step.label} cleanup issue: ${errMsg}`);
+            errors.push({ label: step.label, error: errMsg });
+          }
+        } else {
+          const value = getResultValue(result);
+          if (value)
+            log.info(String(value));
+        }
+      } catch (e) {
+        const errMsg = e.message || "AWS SDK error";
+        log.warn(`${step.label} cleanup skipped: ${errMsg}`);
+        errors.push({ label: step.label, error: errMsg });
+      }
+    }
+    if (errors.length > 0) {
+      log.warn(`Cleanup completed with ${errors.length} issue(s):`);
+      for (const { label, error } of errors)
+        log.warn(`  - ${label}: ${error}`);
+    }
+    await outro("AWS resources have been removed", {
+      startTime,
+      useSeconds: !0
+    });
+    process.exit(ExitCode.Success);
+  });
+  buddy.command("cloud:invalidate-cache", descriptions.invalidateCache).option("--paths [paths]", descriptions.paths, { default: !1 }).option("-p, --project [project]", descriptions.project, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (options) => {
+    log.debug("Running `buddy cloud:invalidate-cache` ...", options);
+    const startTime = await intro("buddy cloud:invalidate-cache"), { confirm } = await prompts({
+      name: "confirm",
+      type: "confirm",
+      message: "Would you like to invalidate the CloudFront cache?"
+    });
+    if (!confirm) {
+      await outro("Exited", { startTime, useSeconds: !0 });
+      process.exit(ExitCode.Success);
+    }
+    log.info("Invalidating the CloudFront cache...");
+    const distributionId = await getCloudFrontDistributionId();
+    if (!distributionId) {
+      await outro("Could not resolve CloudFront distribution ID", { startTime, useSeconds: !0 }, "Ensure your cloud stack is deployed before invalidating cache.");
+      process.exit(ExitCode.FatalError);
+    }
+    const paths = options.paths ? String(options.paths) : "/*", result = await runCommand(`aws cloudfront create-invalidation --distribution-id ${distributionId} --paths ${paths}`, {
+      ...options,
+      cwd: p.projectPath(),
+      stdin: "pipe"
+    });
+    if (isResultError(result)) {
+      await outro("While running the cloud command, there was an issue", { startTime, useSeconds: !0 }, getResultError(result));
+      process.exit(ExitCode.FatalError);
+    }
+    await outro("Exited", { startTime, useSeconds: !0 });
+    process.exit(ExitCode.Success);
+  });
+  buddy.command("cloud:diff", descriptions.diff).option("-p, --project [project]", descriptions.project, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (options) => {
+    log.debug("Running `buddy cloud:diff` ...", options);
+    const startTime = await intro("buddy cloud:diff");
+    try {
+      const { InfrastructureGenerator } = await import("@stacksjs/ts-cloud"), { CloudFormationClient } = await import("@stacksjs/ts-cloud/aws"), { tsCloud: cloudConfig } = await import("~/config/cloud"), environment = process.env.APP_ENV || process.env.NODE_ENV || "production", newTemplate = new InfrastructureGenerator({
+        config: cloudConfig,
+        environment
+      }).generate().toJSON(), stackName = `${cloudConfig.project?.slug || "stacks"}-${environment}`, cfn = new CloudFormationClient(process.env.AWS_REGION || "us-east-1");
+      let currentTemplate = "{}";
+      try {
+        currentTemplate = (await cfn.getTemplate(stackName)).TemplateBody;
+      } catch {
+        log.info("No deployed stack found. Showing full template as diff.");
+      }
+      if (currentTemplate === newTemplate)
+        log.info("No changes detected.");
+      else {
+        log.info("Changes detected between deployed and local template:");
+        log.info(`Current template: ${currentTemplate.length} bytes`);
+        log.info(`New template: ${newTemplate.length} bytes`);
+      }
+    } catch (error) {
+      await outro("While running the cloud diff command, there was an issue", { startTime, useSeconds: !0 }, error.message);
+      process.exit(ExitCode.FatalError);
+    }
+    await outro("Cloud diff complete", { startTime, useSeconds: !0 });
+    process.exit(ExitCode.Success);
+  });
+  buddy.command("cloud:dashboard", descriptions.dashboard).alias("cloud:cockpit").option("--host [host]", descriptions.host, { default: "127.0.0.1" }).option("--port [port]", descriptions.port, { default: "7676" }).option("--env [env]", descriptions.env).option("--verbose", descriptions.verbose, { default: !1 }).action(async (options) => {
+    log.debug("Running `buddy cloud:dashboard` ...", options);
+    const startTime = await intro("buddy cloud:dashboard"), tsCloud = await import("@stacksjs/ts-cloud");
+    if (typeof tsCloud.startLocalDashboardServer !== "function") {
+      await outro("The installed @stacksjs/ts-cloud does not provide the local cockpit yet", { startTime, useSeconds: !0 }, "Update your dependencies (requires @stacksjs/ts-cloud >= 0.5.27).");
+      process.exit(ExitCode.FatalError);
+    }
+    try {
+      const server = await tsCloud.startLocalDashboardServer({
+        host: options.host ? String(options.host) : void 0,
+        port: options.port ? Number(options.port) : void 0,
+        environment: options.env,
+        verbose: !!options.verbose
+      });
+      log.success(`Stacks Cloud cockpit running at ${underline(server.url)}`);
+      log.info(italic("Manage servers, sites, SSH keys and deploys. Press Ctrl+C to stop."));
+      await new Promise(() => {});
+    } catch (error) {
+      await outro("While starting the cloud dashboard, there was an issue", { startTime, useSeconds: !0 }, error?.message ?? String(error));
+      process.exit(ExitCode.FatalError);
+    }
+  });
+  onUnknownSubcommand(buddy, "cloud");
+}

package/dist/commands/commit.d.ts

@@ -0,0 +1,2 @@
+import type { CLI } from '@stacksjs/types';
+export declare function commit(buddy: CLI): void;

package/dist/commands/commit.js

@@ -0,0 +1,16 @@
+import process from "node:process";
+import { runCommit } from "@stacksjs/actions";
+import { log } from "@stacksjs/logging";
+import { onUnknownSubcommand } from "@stacksjs/cli";
+export function commit(buddy) {
+  const descriptions = {
+    commit: "Commit your stashed changes",
+    project: "Target a specific project",
+    verbose: "Enable verbose output"
+  };
+  buddy.command("commit", descriptions.commit).option("-p, --project [project]", descriptions.project, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (options) => {
+    log.debug("Running `buddy commit` ...", options);
+    await runCommit(options);
+  });
+  onUnknownSubcommand(buddy, "commit");
+}

package/dist/commands/completion.d.ts

@@ -0,0 +1,2 @@
+import type { CLI } from '@stacksjs/types';
+export declare function completion(buddy: CLI): void;

package/dist/commands/completion.js

@@ -0,0 +1,143 @@
+import process from "node:process";
+import { log, onUnknownSubcommand } from "@stacksjs/cli";
+export function completion(buddy) {
+  const descriptions = {
+    completion: "Generate shell completion scripts",
+    shell: "Shell type (bash, zsh, fish)"
+  };
+  buddy.command("completion [shell]", descriptions.completion).option("-s, --shell [shell]", descriptions.shell).example("buddy completion bash").example("buddy completion zsh").example("buddy completion fish").example("buddy completion bash > /usr/local/etc/bash_completion.d/buddy").action(async (shell, options) => {
+    log.debug("Running `buddy completion` ...", options);
+    const targetShell = shell || options.shell || "bash", commandNames = (buddy.commands || []).map((cmd) => cmd.name).filter((name) => Boolean(name));
+    switch (targetShell) {
+      case "bash":
+        console.log(generateBashCompletion(commandNames));
+        break;
+      case "zsh":
+        console.log(generateZshCompletion(commandNames));
+        break;
+      case "fish":
+        console.log(generateFishCompletion(commandNames));
+        break;
+      default:
+        console.error(`Unknown shell: ${targetShell}`);
+        console.error("Supported shells: bash, zsh, fish");
+        process.exit(1);
+    }
+  });
+  onUnknownSubcommand(buddy, "completion");
+}
+function generateBashCompletion(commands) {
+  return `# buddy completion for bash
+
+_buddy_completion() {
+    local cur prev commands
+    COMPREPLY=()
+    cur="\${COMP_WORDS[COMP_CWORD]}"
+    prev="\${COMP_WORDS[COMP_CWORD-1]}"
+
+    commands="${commands.join(" ")}"
+
+    # Complete command names
+    if [ $COMP_CWORD -eq 1 ]; then
+        COMPREPLY=( $(compgen -W "$commands" -- "$cur") )
+        return 0
+    fi
+
+    # Complete global flags
+    case "$prev" in
+        buddy|*)
+            COMPREPLY=( $(compgen -W "--help --version --verbose --quiet --debug --no-interaction --env --dry-run --force" -- "$cur") )
+            return 0
+            ;;
+    esac
+}
+
+complete -F _buddy_completion buddy
+
+# Installation:
+# To install this completion script, save it to:
+# - Linux: /etc/bash_completion.d/buddy or ~/.bash_completion
+# - macOS: /usr/local/etc/bash_completion.d/buddy
+#
+# Then reload your shell or run: source ~/.bashrc
+`;
+}
+function generateZshCompletion(commands) {
+  return `#compdef buddy
+
+# buddy completion for zsh
+
+_buddy() {
+    local -a commands
+    commands=(
+${commands.map((cmd) => `    '${cmd}:${cmd} command'`).join(`
+`)}
+    )
+
+    local -a global_flags
+    global_flags=(
+        '--help[Display help message]'
+        '--version[Display version number]'
+        '--verbose[Enable verbose output]'
+        '--quiet[Suppress non-essential output]'
+        '--debug[Enable debug mode]'
+        '--no-interaction[Do not ask interactive questions]'
+        '--env[Target environment]:environment:'
+        '--dry-run[Preview actions without executing]'
+        '--force[Skip confirmation prompts]'
+    )
+
+    _arguments -C \\
+        '1: :->command' \\
+        '*::arg:->args' \\
+        $global_flags
+
+    case $state in
+        command)
+            _describe 'buddy command' commands
+            ;;
+        *)
+            # Add subcommand-specific completions here if needed
+            ;;
+    esac
+}
+
+_buddy "$@"
+
+# Installation:
+# Save this file to a directory in your $fpath, for example:
+# ~/.zsh/completions/_buddy
+#
+# Then add to your ~/.zshrc:
+# fpath=(~/.zsh/completions $fpath)
+# autoload -Uz compinit && compinit
+`;
+}
+function generateFishCompletion(commands) {
+  return `# buddy completion for fish
+
+# Remove old completions
+complete -c buddy -e
+
+# Command completions
+${commands.map((cmd) => `complete -c buddy -n "__fish_use_subcommand" -a "${cmd}" -d "${cmd} command"`).join(`
+`)}
+
+# Global flag completions
+complete -c buddy -l help -d "Display help message"
+complete -c buddy -l version -d "Display version number"
+complete -c buddy -s v -l verbose -d "Enable verbose output"
+complete -c buddy -s q -l quiet -d "Suppress non-essential output"
+complete -c buddy -l debug -d "Enable debug mode"
+complete -c buddy -s n -l no-interaction -d "Do not ask interactive questions"
+complete -c buddy -l env -d "Target environment" -r
+complete -c buddy -l dry-run -d "Preview actions without executing"
+complete -c buddy -s f -l force -d "Skip confirmation prompts"
+
+# Installation:
+# Save this file to:
+# ~/.config/fish/completions/buddy.fish
+#
+# Fish will automatically load it on startup
+`;
+}