Merge pull request #10 from flyingrobots/feature/run-dry-run

feature/run dry run

Author: flyingrobots

AGENTS.md

@@ -151,3 +151,35 @@ For the current backlog, active work, and completed items, see:
 - docs/tasks/complete/
 
 Progress bars are now maintained in `docs/tasks/README.md` (and mirrored into the root README) by `scripts/update-task-progress.sh`.
+
+## Memoir – Release v0.2.0 (The Cut of Your Jib)
+
+### What We Attempted
+Delivered Shiplog v0.2.0 “The Cut of Your Jib”: implemented `git shiplog run`, `git shiplog append`, `git shiplog trust show`, hardened tests, and polished release artifacts. Tag v0.2.0 is live.
+
+### Key Decisions & Why
+- Documented trailer schema (`docs/reference/json-schema.md`) to remove guesswork for consumers.
+- Gave `test/17_append_and_trust.bats` a unique journal per run plus cleanup to stop cross-run failures.
+- Used `release/v0.2.0` as staging branch for the PR/tag to keep history clean.
+
+### What Worked
+- `cmd_run` in `lib/commands.sh` captures structured run metadata and attaches logs as intended.
+- `cmd_append` handles `--json`/stdin payloads and namespace defaults correctly.
+- `cmd_trust show` surfaces trust roster/signers in both table and `--json` forms.
+- Docs (README, `docs/releases/v0.2.0.md`, CHANGELOG) reference real paths/examples and pass review.
+
+### What Failed or Was Painful
+- CI flakiness from lingering journal refs in `test/17_append_and_trust.bats`; required unique env + cleanup trap.
+- Initial release note file misnamed (`v020.md`) and needed cleanup.
+- Too-strict empty-state assertions in the stdin append test caused rerun failures.
+
+### Lessons & Patterns
+- Tests manipulating Git refs must self-clean (`git update-ref -d`) and avoid assuming empty state.
+- Generate unique identifiers per test (`$RANDOM`, `BATS_TEST_NUMBER`) to prevent collisions.
+- Explicit documentation (schema, release notes, README) smooths review.
+
+### Unresolved Threads
+- UNKNOWN whether runbook task `SLT.BETA.015` will ship before next release.
+
+### Next Moves
+- NONE (release tagged and published).

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 ]
+}