feat(core): add preview directives and helper tasks

Author: KercyDing

Onlyfile

@@ -1,4 +1,9 @@
 !echo true
+!preview false
+
+% Internal helper for release builds
+_release_build():
+    cargo build --release
 
 % Run cargo check
 check():
@@ -18,8 +23,7 @@ ci() & check & test:
     echo "CI complete!"
 
 % Install the local only binary
-install() ? @os("windows") shell?=pwsh:
-    cargo build --release
+install() ? @os("windows") & _release_build shell?=pwsh:
     Write-Output "Windows: cannot replace running binary. Run:`n  Copy-Item target/release/only.exe -Destination `$env:USERPROFILE\.cargo\bin\ -Force"
 
 install():

README.md

@@ -10,17 +10,22 @@ Only is a cross-platform task runner built around a real task language.
 Write tasks once, keep one execution model, and get predictable results on **macOS, Linux, and Windows**.
 
 - **Cross-platform by default** — no Git Bash, no `if os()` hacks, no `platforms:` boilerplate
-- **A better task language** — readable task syntax with parameters, guards, serial and parallel dependencies, namespaces, and interpolation
+- **A better task language** — readable task syntax with parameters, guards, serial and parallel dependencies, helper tasks, directives, namespaces, and interpolation
 - **Built for tooling** — the same core model can power execution, diagnostics, editor features, and future visual workflows
 
 ```Onlyfile
+!preview true
+
+_prepare():
+    cargo fmt --all --check
+
 check():
     cargo check
 
 test():
     cargo test
 
-ci() & check & test:
+ci() & _prepare & check & test:
     echo "CI complete"
 
 release() & build & (package, publish):
@@ -53,6 +58,11 @@ Create an `Onlyfile` in your project root:
 
 ```Onlyfile
 !echo true
+!preview false
+
+% Internal helper for release builds.
+_release_build():
+    cargo build --release
 
 % Run cargo check.
 check():
@@ -111,6 +121,7 @@ build():
 
 ```Onlyfile
 !echo true
+!preview true
 
 % Run checks only if cargo is available.
 check() ? @has("cargo"):
@@ -128,9 +139,12 @@ test() ? @has("cargo-nextest"):
 test():
     cargo test
 
-% Install the local binary.
-install() ? @os("windows") shell?=pwsh:
+% Internal helper reused by install on Windows.
+_release_build():
     cargo build --release
+
+% Install the local binary.
+install() ? @os("windows") & _release_build shell?=pwsh:
     Write-Output "Windows: cannot replace running binary. Run:`n  Copy-Item target/release/only.exe -Destination `$env:USERPROFILE\.cargo\bin\ -Force"
 
 install():
@@ -162,9 +176,10 @@ build():
 ## Why Only ✨
 
 - **Actually cross-platform by default** — `deno_task_shell` keeps behavior aligned across macOS, Linux, and Windows
-- **A better task language** — function-style signatures, parameters, defaults, guards, namespaces, and interpolation stay readable
+- **A better task language** — function-style signatures, parameters, defaults, guards, helper tasks, directives, namespaces, and interpolation stay readable
 - **Clear execution flow** — dependencies, planning, and runtime behavior are explicit instead of being buried in shell glue
 - **Better diagnostics and help** — dynamic task listing and structured validation make the terminal experience less guessy
+- **Safer internal workflow composition** — helper tasks stay usable as dependencies without cluttering normal CLI help
 - **Built for tooling, not just execution** — the same pipeline can power CLI, editor features, language servers, and future visual workflows
 
 | Tool | Best fit | Core model | Portability | Tooling headroom |

crates/cli/src/command.rs

@@ -1,13 +1,15 @@
 use crate::args::{CliInput, parse_global_options, parse_with_onlyfile};
-use crate::compile::{compile_for_cli_input_in_dir, ensure_no_error_diagnostics};
+use crate::compile::{
+    CliCompileResult, compile_for_cli_input_in_dir, ensure_no_error_diagnostics, resolve_target,
+};
 use crate::discover::discover_onlyfile;
 use crate::error::{OnlyError, Result};
 use crate::render::{
     render_available_tasks, render_error_message, render_global_help, render_help_hint,
     render_namespace_help,
 };
-use only_engine::ExecutionPlan;
-use only_semantic::DocumentAst;
+use only_engine::{ExecutionPlan, render_command, select_root_task_variant};
+use only_semantic::{DocumentAst, GuardAst, TaskAst};
 use std::path::{Path, PathBuf};
 use std::process::ExitCode;
 
@@ -75,6 +77,7 @@ pub fn run_with(cli: CliInput) -> Result<ExitCode> {
     }
 
     let compiled = compile_for_cli_input_in_dir(&discovered.contents, &cli, discovered.base_dir)?;
+    render_preview_if_enabled(&compiled, &cli)?;
     only_engine::run_plan(&compiled.plan).map_err(|error| OnlyError::runtime(error.to_string()))
 }
 
@@ -150,6 +153,58 @@ pub fn run_plan(plan: &ExecutionPlan) -> Result<ExitCode> {
     only_engine::run_plan(plan).map_err(|error| OnlyError::runtime(error.to_string()))
 }
 
+fn render_preview_if_enabled(compiled: &CliCompileResult, cli: &CliInput) -> Result<()> {
+    if !compiled.plan.preview {
+        return Ok(());
+    }
+
+    let (target, _) = resolve_target(&compiled.compiled, cli)?;
+    let variant = select_root_task_variant(&compiled.compiled.document, &target)
+        .map_err(|error| OnlyError::runtime(error.to_string()))?;
+    eprintln!("{}", render_plan_preview(&compiled.plan, variant)?);
+    Ok(())
+}
+
+fn render_plan_preview(plan: &ExecutionPlan, variant: &TaskAst) -> Result<String> {
+    let mut output = String::from("Preview:\n");
+    output.push_str("  variant: ");
+    output.push_str(&render_task_variant(variant));
+    output.push('\n');
+    output.push_str("  commands:\n");
+
+    for node in &plan.nodes {
+        for command in &node.commands {
+            let rendered = render_command(command, &node.params)
+                .map_err(|error| OnlyError::runtime(error.to_string()))?;
+            output.push_str("    [");
+            output.push_str(&node.name);
+            output.push_str("] ");
+            output.push_str(&rendered);
+            output.push('\n');
+        }
+    }
+
+    Ok(output.trim_end().to_string())
+}
+
+fn render_task_variant(task: &TaskAst) -> String {
+    let mut variant = match &task.namespace {
+        Some(namespace) => format!("{namespace}.{}", task.signature()),
+        None => task.signature().to_string(),
+    };
+
+    if let Some(guard) = &task.guard {
+        variant.push_str(" ? ");
+        variant.push_str(&render_guard(guard));
+    }
+
+    variant
+}
+
+fn render_guard(guard: &GuardAst) -> String {
+    format!("@{}(\"{}\")", guard.kind, guard.argument)
+}
+
 fn run_inner() -> Result<ExitCode> {
     let partial = parse_global_options()?;
 
@@ -192,5 +247,6 @@ fn run_inner() -> Result<ExitCode> {
     }
 
     let compiled = compile_for_cli_input_in_dir(&discovered.contents, &cli, discovered.base_dir)?;
+    render_preview_if_enabled(&compiled, &cli)?;
     only_engine::run_plan(&compiled.plan).map_err(|error| OnlyError::runtime(error.to_string()))
 }

crates/cli/src/compile.rs

@@ -26,7 +26,8 @@ pub fn compile_for_cli(source: &str) -> CliCompileResult {
     let task_name = compiled
         .document
         .tasks
-        .first()
+        .iter()
+        .find(|task| !task.is_helper())
         .map(|task| task.qualified_name().to_string())
         .unwrap_or_default();
     let plan = build_execution_plan(
@@ -101,7 +102,10 @@ pub fn compile_for_cli_input_in_dir(
     })
 }
 
-fn resolve_target(compiled: &SemanticSnapshot, cli: &CliInput) -> Result<(String, Vec<String>)> {
+pub(crate) fn resolve_target(
+    compiled: &SemanticSnapshot,
+    cli: &CliInput,
+) -> Result<(String, Vec<String>)> {
     let namespaces = compiled
         .document
         .namespaces

crates/cli/src/render.rs

@@ -86,7 +86,7 @@ pub fn render_help(document: &DocumentAst) -> StyledStr {
 /// Returns:
 /// User-facing task list with global tasks and namespaces.
 pub fn render_available_tasks(document: &DocumentAst) -> String {
-    let entries = unique_tasks(global_tasks(document))
+    let entries = unique_tasks(global_tasks(document).filter(|task| !task.is_helper()))
         .into_iter()
         .map(|task| {
             (
@@ -257,7 +257,8 @@ fn build_task_command(task: &TaskAst) -> Command {
         .unwrap_or_default();
     let mut cmd = Command::new(task.name.to_string())
         .styles(cli_styles())
-        .about(about);
+        .about(about)
+        .hide(task.is_helper());
 
     for (index, param) in task.params.iter().enumerate() {
         let arg = if let Some(default) = &param.default_value {
@@ -520,6 +521,27 @@ smoke():
         assert!(help.starts_with("Developer workflow."));
     }
 
+    #[test]
+    fn hides_helper_tasks_from_rendered_outputs() {
+        let document = parse_onlyfile(
+            "% Run tests.\n_test_helper():\n    cargo test\ntest():\n    cargo test\n\n[dev]\n_workflow():\n    echo hidden\nworkflow():\n    echo ok\n",
+        )
+        .expect("document should parse");
+
+        let listing = render_available_tasks(&document);
+        assert!(listing.contains("test"));
+        assert!(!listing.contains("_test_helper"));
+        assert!(!listing.contains("_workflow"));
+
+        let root_help = render_help(&document).to_string();
+        assert!(root_help.contains("test"));
+        assert!(!root_help.contains("_test_helper"));
+
+        let namespace_help = render_namespace_help(&document, &document.namespaces[0]).to_string();
+        assert!(namespace_help.contains("workflow"));
+        assert!(!namespace_help.contains("_workflow"));
+    }
+
     #[test]
     fn allows_guarded_task_variants_without_duplicate_subcommand_panic() {
         let document = parse_onlyfile(

crates/cli/tests/cli.rs

@@ -1032,6 +1032,70 @@ fn run_with_rejects_error_diagnostics_before_execution() {
     fs::remove_dir_all(root).expect("temp tree should be removed");
 }
 
+#[test]
+fn rejects_direct_helper_task_execution_via_run_with() {
+    let _cwd_lock = cwd_lock();
+    let root = temp_case_dir("only-runtime-helper-task");
+    let onlyfile_path = root.join("Onlyfile");
+    fs::write(&onlyfile_path, "_prepare():\n    echo helper\n")
+        .expect("Onlyfile should be written");
+
+    let input = CliInput {
+        onlyfile_path: Some(onlyfile_path),
+        print_discovered_path: false,
+        top_level_help_requested: false,
+        top_level_version_requested: false,
+        task_path: vec!["_prepare".into()],
+        parameter_overrides: vec![],
+    };
+
+    let error = run_with(input).expect_err("helper task should not execute directly");
+    assert_eq!(
+        error.to_string(),
+        "helper task '_prepare' cannot be invoked directly"
+    );
+
+    fs::remove_dir_all(root).expect("temp tree should be removed");
+}
+
+#[cfg(unix)]
+#[test]
+fn preview_prints_selected_variant_and_commands_before_execution() {
+    let _cwd_lock = cwd_lock();
+    let temp_dir = TempDir::new("preview-cli-unix");
+    let onlyfile_path = temp_dir.path().join("Onlyfile");
+    let current_os = std::env::consts::OS;
+    let other_os = if current_os == "windows" {
+        "linux"
+    } else {
+        "windows"
+    };
+    fs::write(
+        &onlyfile_path,
+        format!(
+            "!preview true\nprobe() ? @os(\"{current_os}\"):\n    printf 'guarded\\n'\nprobe() ? @os(\"{other_os}\"):\n    printf 'skipped\\n'\nprobe():\n    printf 'fallback\\n'\n"
+        ),
+    )
+    .expect("Onlyfile should be written");
+
+    let output = Command::new(cli_binary_path())
+        .arg("probe")
+        .current_dir(temp_dir.path())
+        .output()
+        .expect("CLI process should run");
+
+    let stdout = String::from_utf8(output.stdout).expect("stdout should be valid utf-8");
+    let stderr = String::from_utf8(output.stderr).expect("stderr should be valid utf-8");
+    let plain_stdout = strip_ansi(&stdout);
+    let plain_stderr = strip_ansi(&stderr);
+
+    assert_eq!(output.status.code(), Some(0), "stderr was: {stderr}");
+    assert!(plain_stderr.contains("Preview:"));
+    assert!(plain_stderr.contains(&format!("variant: probe() ? @os(\"{current_os}\")")));
+    assert!(plain_stderr.contains("[probe] printf 'guarded"));
+    assert!(plain_stdout.contains("[probe] guarded"));
+}
+
 #[test]
 fn exposes_workspace_cli_version() {
     assert_eq!(version_string(), env!("CARGO_PKG_VERSION"));

crates/cli/tests/compile.rs

@@ -7,6 +7,13 @@ fn compiles_in_memory_source_without_fs() {
     assert_eq!(compiled.plan.nodes[0].name, "check");
 }
 
+#[test]
+fn skips_helper_task_when_picking_default_in_memory_target() {
+    let compiled = compile_for_cli("_prepare():\n    echo helper\ncheck():\n    echo ok\n");
+    assert!(compiled.diagnostics.is_empty());
+    assert_eq!(compiled.plan.nodes[0].name, "check");
+}
+
 #[test]
 fn compiles_namespaced_first_task_into_plan() {
     let compiled = compile_for_cli("[dev]\nserve():\n    echo ok\n");
@@ -56,6 +63,25 @@ fn compiles_selected_global_task_with_named_override() {
     );
 }
 
+#[test]
+fn rejects_direct_invocation_of_helper_task_for_semantic_cli_compile() {
+    let cli = CliInput {
+        onlyfile_path: None,
+        print_discovered_path: false,
+        top_level_help_requested: false,
+        top_level_version_requested: false,
+        task_path: vec!["_prepare".into()],
+        parameter_overrides: vec![],
+    };
+    let error = compile_for_cli_input("_prepare():\n    echo helper\n", &cli)
+        .expect_err("helper target should fail semantic CLI compile");
+
+    assert_eq!(
+        error.to_string(),
+        "helper task '_prepare' cannot be invoked directly"
+    );
+}
+
 #[test]
 fn rejects_namespace_without_task_target_for_semantic_cli_compile() {
     let cli = CliInput {

crates/engine/src/lib.rs

@@ -14,6 +14,6 @@ pub use interpolate::interpolate as render_command;
 pub use planner::try_build_execution_plan;
 pub use planner::{
     ExecutionNode, ExecutionPlan, Invocation, PlanError, PlanParam, build_execution_plan,
-    try_build_execution_plan_in_dir,
+    select_root_task_variant, try_build_execution_plan_in_dir,
 };
 pub use runtime::run_plan;