From ab5c0392c6f98bfbc875f1ca61a1965f3c9491fc Mon Sep 17 00:00:00 2001
From: Ivan Histand <ivan@badgeretl.com>
Date: Tue, 16 Jun 2026 17:08:51 -0500
Subject: [PATCH] chore(cli): output-focused help text for compile selection
 flags

The --actions/--tags/--include-deps/--include-dependents flags on `compile`
reused `run`'s help text ("...to run", "...will also be run"), which reads
wrong for compile (it filters the printed graph, it doesn't execute). Add
compile-specific variants of the four options with output-focused wording,
sharing the run flags' names, coerce, and validation. Behavior unchanged.

Extends the compile help test to assert the flags and new wording appear.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 cli/index.ts           | 41 +++++++++++++++++++++++++++++++++++++----
 cli/index_help_test.ts |  6 ++++++
 2 files changed, 43 insertions(+), 4 deletions(-)

diff --git a/cli/index.ts b/cli/index.ts
index 49ff2cd2..73289907 100644
--- a/cli/index.ts
+++ b/cli/index.ts
@@ -217,6 +217,39 @@ const includeDependentsOption = option(
   }
 );
 
+// `compile` reuses the same selection flags as `run`, but it filters the printed
+// graph rather than executing actions -- so it gets output-focused help text.
+// Same flag names (so argv indexing and the shared validation still apply); only
+// the describe strings differ.
+const compileActionsOption = {
+  ...actionsOption,
+  option: {
+    ...actionsOption.option,
+    describe: "A list of action names or patterns to include in the output. Can include '*' wildcards."
+  }
+};
+
+const compileTagsOption = {
+  ...tagsOption,
+  option: { ...tagsOption.option, describe: "A list of tags to filter the output to." }
+};
+
+const compileIncludeDepsOption = {
+  ...includeDepsOption,
+  option: {
+    ...includeDepsOption.option,
+    describe: "If set, dependencies of selected actions are also included in the output."
+  }
+};
+
+const compileIncludeDependentsOption = {
+  ...includeDependentsOption,
+  option: {
+    ...includeDependentsOption.option,
+    describe: "If set, dependents (downstream) of selected actions are also included in the output."
+  }
+};
+
 const credentialsOption = option(
   "credentials",
   {
@@ -463,10 +496,10 @@ export function runCli() {
           dotOutputOption,
           timeoutOption,
           quietCompileOption,
-          actionsOption,
-          tagsOption,
-          includeDepsOption,
-          includeDependentsOption,
+          compileActionsOption,
+          compileTagsOption,
+          compileIncludeDepsOption,
+          compileIncludeDependentsOption,
           option(
             verboseOptionName,
             {
diff --git a/cli/index_help_test.ts b/cli/index_help_test.ts
index 1a8783d4..7ac40fef 100644
--- a/cli/index_help_test.ts
+++ b/cli/index_help_test.ts
@@ -54,6 +54,12 @@ suite("help command", () => {
     expect(output).to.include("--watch");
     expect(output).to.include("--json");
     expect(output).to.include("--quiet");
+    expect(output).to.include("--actions");
+    expect(output).to.include("--tags");
+    expect(output).to.include("--include-deps");
+    expect(output).to.include("--include-dependents");
+    // Compile-specific wording: filters output rather than executing actions.
+    expect(output).to.include("include in the output");
   });
 
   test("shows help for 'test' command", async () => {