diff --git a/Sources/LucaCLI/LucaCLI.docc/Tutorials/Luca.tutorial b/Sources/LucaCLI/LucaCLI.docc/Tutorials/Luca.tutorial index 61a8e29..53cfa87 100644 --- a/Sources/LucaCLI/LucaCLI.docc/Tutorials/Luca.tutorial +++ b/Sources/LucaCLI/LucaCLI.docc/Tutorials/Luca.tutorial @@ -23,4 +23,10 @@ @TutorialReference(tutorial: "doc:InstallingSkills") } + + @Chapter(name: "Running Pipelines") { + Define and run repeatable task pipelines with parameters and conditions. + + @TutorialReference(tutorial: "doc:RunningPipelines") + } } diff --git a/Sources/LucaCLI/LucaCLI.docc/Tutorials/Resources/dry-run-output.txt b/Sources/LucaCLI/LucaCLI.docc/Tutorials/Resources/dry-run-output.txt new file mode 100644 index 0000000..98188ee --- /dev/null +++ b/Sources/LucaCLI/LucaCLI.docc/Tutorials/Resources/dry-run-output.txt @@ -0,0 +1,20 @@ +[DRY RUN] Pipeline: build + +Parameters: + configuration = release (override) + upload = false (default) + +Task 1: Build + Command: swift build --configuration ${configuration} + Tools: swift ✓ + +Task 2: Test + Command: swift test + When: ${configuration} == debug → skip + +Task 3: Upload artifact + Command: ./scripts/upload.sh + When: ${upload} == true → skip + Flags: continue-on-error + +No tasks executed. diff --git a/Sources/LucaCLI/LucaCLI.docc/Tutorials/Resources/luca-run-build.sh b/Sources/LucaCLI/LucaCLI.docc/Tutorials/Resources/luca-run-build.sh new file mode 100644 index 0000000..33f4b24 --- /dev/null +++ b/Sources/LucaCLI/LucaCLI.docc/Tutorials/Resources/luca-run-build.sh @@ -0,0 +1 @@ +luca run build diff --git a/Sources/LucaCLI/LucaCLI.docc/Tutorials/Resources/luca-run-dry-run.sh b/Sources/LucaCLI/LucaCLI.docc/Tutorials/Resources/luca-run-dry-run.sh new file mode 100644 index 0000000..f929fc8 --- /dev/null +++ b/Sources/LucaCLI/LucaCLI.docc/Tutorials/Resources/luca-run-dry-run.sh @@ -0,0 +1 @@ +luca run build --dry-run --param configuration=release diff --git a/Sources/LucaCLI/LucaCLI.docc/Tutorials/Resources/luca-run-params.sh b/Sources/LucaCLI/LucaCLI.docc/Tutorials/Resources/luca-run-params.sh new file mode 100644 index 0000000..9f7ef63 --- /dev/null +++ b/Sources/LucaCLI/LucaCLI.docc/Tutorials/Resources/luca-run-params.sh @@ -0,0 +1 @@ +luca run build --param configuration=release --param upload=true diff --git a/Sources/LucaCLI/LucaCLI.docc/Tutorials/Resources/pipeline-build-01.yml b/Sources/LucaCLI/LucaCLI.docc/Tutorials/Resources/pipeline-build-01.yml new file mode 100644 index 0000000..2234255 --- /dev/null +++ b/Sources/LucaCLI/LucaCLI.docc/Tutorials/Resources/pipeline-build-01.yml @@ -0,0 +1,3 @@ +tasks: + - name: Build + command: swift build diff --git a/Sources/LucaCLI/LucaCLI.docc/Tutorials/Resources/pipeline-build-02.yml b/Sources/LucaCLI/LucaCLI.docc/Tutorials/Resources/pipeline-build-02.yml new file mode 100644 index 0000000..b904de3 --- /dev/null +++ b/Sources/LucaCLI/LucaCLI.docc/Tutorials/Resources/pipeline-build-02.yml @@ -0,0 +1,6 @@ +tasks: + - name: Build + command: swift build + + - name: Test + command: swift test diff --git a/Sources/LucaCLI/LucaCLI.docc/Tutorials/Resources/pipeline-build-03.yml b/Sources/LucaCLI/LucaCLI.docc/Tutorials/Resources/pipeline-build-03.yml new file mode 100644 index 0000000..c16b6bc --- /dev/null +++ b/Sources/LucaCLI/LucaCLI.docc/Tutorials/Resources/pipeline-build-03.yml @@ -0,0 +1,11 @@ +parameters: + - name: configuration + description: Build configuration + default: debug + +tasks: + - name: Build + command: swift build --configuration ${configuration} + + - name: Test + command: swift test diff --git a/Sources/LucaCLI/LucaCLI.docc/Tutorials/Resources/pipeline-build-04.yml b/Sources/LucaCLI/LucaCLI.docc/Tutorials/Resources/pipeline-build-04.yml new file mode 100644 index 0000000..4d8ab1c --- /dev/null +++ b/Sources/LucaCLI/LucaCLI.docc/Tutorials/Resources/pipeline-build-04.yml @@ -0,0 +1,20 @@ +parameters: + - name: configuration + description: Build configuration + default: debug + - name: upload + description: Upload the build artifact after building + default: "false" + +tasks: + - name: Build + command: swift build --configuration ${configuration} + + - name: Test + command: swift test + when: ${configuration} == debug + + - name: Upload artifact + command: ./scripts/upload.sh + when: ${upload} == true + continue-on-error: true diff --git a/Sources/LucaCLI/LucaCLI.docc/Tutorials/RunningPipelines.tutorial b/Sources/LucaCLI/LucaCLI.docc/Tutorials/RunningPipelines.tutorial new file mode 100644 index 0000000..d49cb52 --- /dev/null +++ b/Sources/LucaCLI/LucaCLI.docc/Tutorials/RunningPipelines.tutorial @@ -0,0 +1,120 @@ +@Tutorial(time: 10) { + @Intro(title: "Running Pipelines") { + Learn how to define and run repeatable task pipelines using Luca's + built-in pipeline engine. + + In this tutorial, you'll create a pipeline file, run it with + `luca run`, add parameters to make it reusable, and use conditions + to skip tasks at runtime. + } + + @Section(title: "Create a Pipeline File") { + @ContentAndMedia { + A pipeline is a YAML file that lists an ordered set of tasks. + Each task has a name and a shell command to execute. Luca searches + for pipeline files by name in the current directory and in a + `pipelines/` subdirectory. + } + + @Steps { + @Step { + Create a `pipelines/` directory in your project root and add + a new file named `build.yml`. Start with a single `Build` + task. + + @Code(name: "pipelines/build.yml", file: "pipeline-build-01.yml") + } + + @Step { + Add a second task to run your tests after the build. Tasks + execute in the order they are declared, and Luca stops at the + first failure. + + @Code(name: "pipelines/build.yml", file: "pipeline-build-02.yml") + } + } + } + + @Section(title: "Run the Pipeline") { + @ContentAndMedia { + Use `luca run` with the pipeline name to execute it. Luca resolves + the name to the YAML file automatically — you don't need to provide + the path or the extension. + } + + @Steps { + @Step { + From your project root, run the pipeline by name. Luca prints + each task's name before executing it and exits non-zero if any + task fails. + + @Code(name: "Terminal", file: "luca-run-build.sh") + } + } + } + + @Section(title: "Add Parameters") { + @ContentAndMedia { + Parameters let you write a single pipeline that behaves differently + depending on values provided at runtime. Declare them in a + `parameters:` block and reference them with `${name}` inside any + task command. + + Parameters with a `default:` are optional. Parameters without one + are required — Luca exits with an error if no value is supplied. + } + + @Steps { + @Step { + Add a `parameters:` block and a `configuration` parameter with + a default of `debug`. Use it in the `Build` task command. + + @Code(name: "pipelines/build.yml", file: "pipeline-build-03.yml") + } + + @Step { + Add an `upload` parameter to control whether a build artifact + is uploaded. Then add a task that uses it as a condition and + mark it with `continue-on-error: true` so a failure there + doesn't abort the pipeline. + + @Code(name: "pipelines/build.yml", file: "pipeline-build-04.yml") + } + + @Step { + Pass values at runtime with `--param`. Multiple flags are + supported. + + @Code(name: "Terminal", file: "luca-run-params.sh") + } + } + } + + @Section(title: "Preview with Dry Run") { + @ContentAndMedia { + The `--dry-run` flag validates the pipeline and prints a full + execution preview without running any tasks. It shows each + parameter's resolved value, which tools are available, and whether + conditional tasks would run or be skipped. + + Use dry run to verify your pipeline before committing it or before + running it in CI. + } + + @Steps { + @Step { + Run the pipeline with `--dry-run` and supply a parameter + override to preview what would happen in a release build. + + @Code(name: "Terminal", file: "luca-run-dry-run.sh") + } + + @Step { + Luca prints the resolved parameter values, tool availability, + and the outcome of each condition. No tasks are executed. + + @Code(name: "Output", file: "dry-run-output.txt") + } + } + } +}