Batch Script Progress

Make generated batch scripts observable while they run, without changing their processing contract. Design start, periodic progress, per-item failure, and final-summary output together with result streams and exit status. A progress-bar library alone does not establish this contract.

1. Fix the existing contract

Read the script, callers, and nearby tests before editing. Identify:

• Input unit, known or unknown total, and whether enumeration is lazy.
• Existing stdout format and consumers, runtime version, and interactive versus redirected execution.
• Continue-on-error or fail-fast policy, retry rules, skip rules, transaction boundaries, and cancellation behavior.
• Existing exit codes and what callers treat as success.

Preserve these decisions. Do not add retries, parallelism, dependencies, or a new failure policy just to add progress output. If partial failures currently return zero, report the partial outcome honestly while keeping that exit contract. If the contract is missing or contradictory, ask for the decision that changes behavior; do not silently make it.

2. Define the output contract before implementation

Choose a small, stable vocabulary and fields, reusing the repository logger where suitable:

• Start: operation name, total or explicit unknown, and initial counters. Emit before expensive enumeration; discovery itself may need progress.
• Progress: processed, succeeded, failed, skipped, total or unknown, and elapsed time. Add a sanitized current-item identifier only when useful.
• Item failure: safe identifier, failure category or sanitized reason, and whether processing will continue. Emit when observed, independently of the normal progress interval.
• Summary: completed, partial, failed, or cancelled; final counters; elapsed time; known unprocessed count if available; and the exit status required by the existing contract.

Define processed = succeeded + failed + skipped for items that reached a terminal outcome. Keep in-flight and not-started items separate. Count each item once; retry attempts are not additional processed items. Do not label an item successful before its required commit, write, or acknowledgement. If a transaction rolls back, report rolled-back work rather than claiming durable success.

For an unknown total, report counts without a fabricated percentage, ETA, or remaining count. Do not materialize a stream just to count it. For zero items, emit start and summary with zero counts; never divide by zero.

3. Choose output streams and cadence

Reserve stdout for the established machine-readable result, pipeline objects, or protocol. Put progress and diagnostics on a separate channel; stderr is the portable default for standalone CLI scripts. Stderr output alone does not imply failure: callers must use the agreed exit code and result contract. Verify callers that treat any stderr as failure before changing their output. If stdout is reserved and stderr is incompatible, use an existing compatible logger or sink only when the caller already supports it. Do not move progress to stdout or another stream with changed semantics. If no compatible channel exists, stop and ask whether the output contract may change, or report that progress cannot be added safely.

Use a bounded cadence, such as every configured number of items or elapsed interval, rather than unconditionally logging every item. Emit start, failures, and summary regardless of that cadence. Preserve required per-item audit records separately. Avoid unbounded in-memory failure lists and repeated stack traces. Redact credentials, query parameters, personal data, and sensitive paths before formatting; do not dump raw exceptions or whole input records by default.

Use monotonic time for intervals and duration. Ensure output is flushed or drained so notifications arrive before exit. Use plain newline-delimited records under redirection; enable terminal rewriting or colors only for an appropriate TTY. Keep log-field meanings consistent across languages, not necessarily their exact formatting or libraries.

…