fix(cli): completions resilient, improve help text for destructive commands

- Replace completions stubs with Cliffy CompletionsCommand for bash/zsh/fish
- Add best-effort stack-name completion with graceful fallback on missing config
- Add detailed help descriptions for down (destructive warning), secrets (sops/age dependency), sync (drift detection), reload (in-place redeploy)
- Add stub exports for in-progress env features to unblock compilation
- Add tests for completions shells and enhanced help text

Author: wax911

src/cli/mod.ts

@@ -565,6 +565,11 @@ export function buildCli(): Command {
 
   // --- sync (issue #6) ---
   cli.command("sync", "Full sync pipeline: generate, render, and deploy stacks.")
+    .description(
+      "Performs drift detection by comparing generated stack content against\n" +
+        "canonical files. Only deploys stacks that have changed. Use --dry-run\n" +
+        "to preview without deploying.",
+    )
     .option("--dry-run", "Preview sync without deploying.")
     .option("--config <path:string>", "Explicit config file path.")
     .option("--profile <name:string>", "Use a specific profile.")
@@ -762,7 +767,12 @@ export function buildCli(): Command {
     });
 
   // --- reload (issue #9) ---
-  cli.command("reload", "Re-render and redeploy only changed stacks without tearing them down.")
+  cli.command("reload", "Re-render and redeploy stacks in-place without tearing them down.")
+    .description(
+      "Compares current deployed config against desired state. Only changed\n" +
+        "stacks are updated, minimizing service disruption compared to a full\n" +
+        "down-and-up cycle.",
+    )
     .option("--skip-generate", "Only re-render and re-deploy, do not regenerate stacks.")
     .option("--follow-logs", "Stream logs for deployed stacks after reload.")
     .option("--stacks <names:string>", "Comma-separated list of stack names to reload.")
@@ -830,7 +840,15 @@ export function buildCli(): Command {
     });
 
   // --- secrets (issue #7) ---
-  const secretsCmd = cli.command("secrets", "Manage SOPS/age encrypted secrets.");
+  const secretsCmd = cli.command(
+    "secrets",
+    "Manage SOPS/age encrypted secrets for stack env files.",
+  )
+    .description(
+      "Requires sops (https://github.com/getsops/sops) and age\n" +
+        "(https://github.com/FiloSottile/age) to be installed on the host.\n" +
+        "Run ` stackctl secrets check ` to verify tooling availability.",
+    );
 
   secretsCmd.command("encrypt", "Encrypt .env files to encrypted output.")
     .arguments("[files...:string]")

src/cli/mod_test.ts

@@ -47,3 +47,47 @@ Deno.test("buildCli version is set", () => {
   const cmd = buildCli();
   assertEquals(cmd.getVersion(), "0.1.0-dev");
 });
+
+Deno.test("completions subcommand has bash, zsh, fish shells", () => {
+  const cmd = buildCli();
+  const completions = cmd.getCommand("completions");
+  assertEquals(completions !== undefined, true, "completions command should exist");
+
+  // CompletionsCommand provides bash, zsh, fish subcommands
+  const bash = completions!.getCommand("bash");
+  const zsh = completions!.getCommand("zsh");
+  const fish = completions!.getCommand("fish");
+
+  assertEquals(bash !== undefined, true, "bash completions should be available");
+  assertEquals(zsh !== undefined, true, "zsh completions should be available");
+  assertEquals(fish !== undefined, true, "fish completions should be available");
+});
+
+Deno.test("enhanced help descriptions for destructive/external-tool commands", () => {
+  const cmd = buildCli();
+
+  // down - should warn about destructive operation in full text
+  const downCmd = cmd.getCommand("down");
+  assertEquals(downCmd !== undefined, true);
+  const downText = downCmd!.getDescription();
+  assertEquals(downText.includes("WARNING"), true);
+  assertEquals(downText.includes("destructive"), true);
+
+  // secrets - should mention sops/age dependency in full description
+  const secretsCmd = cmd.getCommand("secrets");
+  assertEquals(secretsCmd !== undefined, true);
+  const secretsText = secretsCmd!.getDescription();
+  assertEquals(secretsText.includes("sops"), true);
+
+  // sync - should mention drift detection in full description
+  const syncCmd = cmd.getCommand("sync");
+  assertEquals(syncCmd !== undefined, true);
+  const syncText = syncCmd!.getDescription();
+  assertEquals(syncText.includes("drift"), true);
+
+  // reload - short description mentions in-place; full description mentions in-place/disruption
+  const reloadCmd = cmd.getCommand("reload");
+  assertEquals(reloadCmd !== undefined, true);
+  const reloadText = reloadCmd!.getDescription();
+  assertEquals(reloadText.includes("minimizing service disruption"), true);
+});