feat(run): add dry-run option

Author: flyingrobots

docs/features/command-reference.md

@@ -41,8 +41,8 @@ A concise, code-sourced reference for Shiplog commands, flags, and examples. Glo
   - Usage:
     - Success case: `git shiplog run --service deploy --reason "Smoke test" -- env printf hi`
     - Failure case: `git shiplog run --service deploy --status-failure failed -- false`
-  - Flags: `--service`, `--reason`, `--status-success`, `--status-failure`, `--ticket`, `--region`, `--cluster`, `--namespace`, `--env`.
-  - Notes: captures stdout/stderr to a temporary log that is attached as a git note (skipped if empty) and merges `{run:{...}}` into the JSON trailer via `SHIPLOG_EXTRA_JSON`. See `docs/reference/json-schema.md` for the structured payload.
+  - Flags: `--service`, `--reason`, `--status-success`, `--status-failure`, `--ticket`, `--region`, `--cluster`, `--namespace`, `--env`, `--dry-run`.
+  - Notes: captures stdout/stderr to a temporary log that is attached as a git note (skipped if empty) and merges `{run:{...}}` into the JSON trailer via `SHIPLOG_EXTRA_JSON`. `--dry-run` prints the command that would execute and exits without running it or writing a journal entry. See `docs/reference/json-schema.md` for the structured payload.
 
 - `ls [ENV] [LIMIT]`
   - Purpose: list recent entries.

docs/features/run.md

@@ -1,11 +1,12 @@
 # Run Command
 
 ## Summary
-`git shiplog run` wraps a shell command, captures its stdout/stderr, and records the execution as a Shiplog journal entry. The command output is saved as a git note, and the structured trailer gains a `run` payload describing the invocation.
+`git shiplog run` wraps a shell command, captures its stdout/stderr, and records the execution as a Shiplog journal entry. The command output is saved as a git note, and the structured trailer gains a `run` payload describing the invocation. Use `--dry-run` to preview what would happen without executing the command or writing an entry.
 
 ## Usage
 ```bash
 git shiplog run --service deploy --reason "Smoke test" -- env printf hi
+git shiplog run --dry-run --service deploy --reason "Smoke test" -- env printf hi
 ```
 
 - `--service` is required in non-interactive mode (and highly recommended in general).
@@ -14,6 +15,7 @@ git shiplog run --service deploy --reason "Smoke test" -- env printf hi
 
 ## Behavior
 - Captures stdout/stderr to a temporary file. When not in boring mode, output is also streamed to your terminal via `tee`.
+- `--dry-run` prints the wrapped command, returns exit code 0, and skips execution, journal writes, and log attachment.
 - Sets `SHIPLOG_BORING=1` and `SHIPLOG_ASSUME_YES=1` while calling `git shiplog write` so no prompts fire.
 - Populates `SHIPLOG_EXTRA_JSON` with:
   ```json
@@ -34,6 +36,7 @@ git shiplog run --service deploy --reason "Smoke test" -- env printf hi
 - Returns the wrapped command’s exit code so it can be chained in scripts or CI pipelines.
 
 ## Options
+- `--dry-run` — Print the command that would execute, then exit without running it or writing a journal entry.
 - `--env <name>` — Target journal environment (defaults to `SHIPLOG_ENV` or `prod`).
 - `--service <name>` — Service/component; required when prompts are disabled.
 - `--reason <text>` — Optional free-form description.

lib/commands.sh

@@ -394,6 +394,7 @@ cmd_run() {
   local region="${SHIPLOG_REGION:-}"
   local cluster="${SHIPLOG_CLUSTER:-}"
 
+  local dry_run=0
   local -a run_argv=()
   while [ $# -gt 0 ]; do
     case "$1" in
@@ -433,6 +434,8 @@ cmd_run() {
         shift; cluster="${1:-}"; shift; continue ;;
       --cluster=*)
         cluster="${1#*=}"; shift; continue ;;
+      --dry-run)
+        dry_run=1; shift; continue ;;
       --)
         shift
         while [ $# -gt 0 ]; do run_argv+=("$1"); shift; done
@@ -453,6 +456,26 @@ cmd_run() {
     die "shiplog: --service (or SHIPLOG_SERVICE) is required for run"
   fi
 
+  local -a quoted_cmd=()
+  local arg
+  for arg in "${run_argv[@]}"; do
+    quoted_cmd+=("$(printf '%q' "$arg")")
+  done
+  local cmd_display
+  cmd_display="${quoted_cmd[*]}"
+
+  if [ "$dry_run" -eq 1 ]; then
+    local dry_message="shiplog run --dry-run: would execute: $cmd_display"
+    if shiplog_can_use_bosun; then
+      local bosun
+      bosun=$(shiplog_bosun_bin)
+      "$bosun" style --title "Dry Run" -- "🚫 ${dry_message#shiplog run --dry-run: }"
+    else
+      printf '%s\n' "ℹ️ $dry_message"
+    fi
+    return 0
+  fi
+
   local started_at finished_at
   local start_epoch end_epoch duration_s
   local log_path; log_path=$(mktemp) || die "shiplog: failed to allocate temp log"
@@ -494,14 +517,6 @@ cmd_run() {
     log_attached_bool="true"
   fi
 
-  local -a quoted_cmd=()
-  local arg
-  for arg in "${run_argv[@]}"; do
-    quoted_cmd+=("$(printf '%q' "$arg")")
-  done
-  local cmd_display
-  cmd_display="${quoted_cmd[*]}"
-
   local argv_json
   argv_json=$(printf '%s\n' "${run_argv[@]}" | jq -R . | jq -s .)
 

test/10_run_command.bats

@@ -75,3 +75,19 @@ teardown() {
   [ "$status" -eq 0 ]
   [ "$output" = "false" ]
 }
+
+@test "run dry-run previews without executing" {
+  rm -f dry-run-file
+  [ ! -e dry-run-file ]
+
+  run git show-ref "${REF_ROOT}/journal/prod"
+  [ "$status" -ne 0 ]
+
+  run bash -lc 'git shiplog run --dry-run --service test --reason "no-op" -- touch dry-run-file'
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"would execute: touch dry-run-file"* ]]
+  [ ! -e dry-run-file ]
+
+  run git show-ref "${REF_ROOT}/journal/prod"
+  [ "$status" -ne 0 ]
+}