fix: process trace Phase 2 — trap chaining, stack flush, portability by fentas · Pull Request #173 · arg-sh/argsh

fentas · 2026-05-10T10:16:03Z

Summary

Phase 2 of process trace (#99):

Fixes from Phase 1 Copilot review:

Chain DEBUG/EXIT traps instead of overwriting (preserves error::stacktrace etc.)
Flush pending function exit events in exit hook
Use printf instead of echo for trace writes
Safe if/else/fi guard for minified bundling
Fix version docs (v0.11.0)

Phase 2: argsh-dap --trace

argsh-dap --trace output.md -- script.sh [args] — headless execution tracing
Reuses DEBUG trap prelude and FIFO infrastructure from DAP debugger
After script exits, enriches trace with argsh_syntax analysis (command tree, field annotations, import tree)
Full markdown output with header, execution timeline, :args variables, summary

Tests:

6 new bash trace tests (header, functions, :args, summary, exit code, trap chaining)
5 integration tests for argsh-dap --trace mode
3 existing tests refactored for DEBUG trap compatibility

Docs:

New docs/development/tools/trace.mdx — full trace feature documentation
Updated debugger docs with --trace cross-reference
Updated sidebars

Closes #99

🤖 Generated with Claude Code

- Chain DEBUG/EXIT traps with existing handlers instead of overwriting - Flush pending stack entries in exit hook (catches missed exits) - Use printf instead of echo for trace output (portability) - Remove unsafe return/exit guard — use if/else/fi structure - Fix version in docs (v0.11.0 not v0.9.0) Addresses Copilot review on #168 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

This PR iterates on the ARGSH_TRACE “process trace” feature (Phase 2) to make tracing safer to enable in real scripts by avoiding top-level guard returns (for minified bundling), improving portability of trace writes, and attempting to preserve existing DEBUG/EXIT traps.

Changes:

Replace the top-level return/exit guard with an if/else/fi block so the file can be safely bundled/minified.
Switch trace line writes from echo to printf, and flush any remaining stack frames in the EXIT hook.
Update documentation to reflect the correct version where ARGSH_TRACE was introduced.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
libraries/trace.sh	Trap chaining changes, `printf`-based writes, and EXIT-time stack flush for ARGSH_TRACE.
docs/environment-variables.mdx	Updates the “New in …” version for `ARGSH_TRACE`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Add `argsh-dap --trace <out.md> -- <script> [args...]` that runs a bash script with the DEBUG trap prelude, collects all function entry/exit events via FIFO, then writes a structured markdown trace enriched with argsh_syntax analysis (field types, command tree, import tree). - TRACE_PRELUDE: fire-and-forget DEBUG trap (no blocking on ctl FIFO) - run_trace_mode(): FIFO setup, event collection, markdown rendering - render_trace_markdown(): builds header, command tree, execution table, args details, import tree, and summary sections - 5 integration tests covering output format, function tracing, error cases, and non-zero exit code reporting Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…feature Add 6 new test cases for ARGSH_TRACE covering header fields, function entry/exit recording, :args variable dumps, summary section validation, non-zero exit codes, and EXIT trap chaining. Fix existing 3 trace tests to use standalone scripts instead of subshells (avoids bats DEBUG trap conflicts). Create docs/development/tools/trace.mdx documenting both ARGSH_TRACE env var (Phase 1) and argsh-dap --trace (Phase 2) methods with example output and use cases. Update debugger.mdx to cross-reference trace mode and add trace page to sidebars.js. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Hold TempDir for automatic cleanup on all exit paths (no .keep()) - Remove unused _exit_code_fifo (process exit code used instead) - Scan first 10 lines for argsh detection (not just shebang) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 7 comments.

Copilot

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 6 comments.

Copilot

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 5 comments.

…ection - Preserve $? for chained EXIT handlers via save/restore pattern - Route stack flush through __argsh_trace_write for consistency - Cap markdown indent at 1 level to avoid CommonMark code blocks - Tighten argsh detection: check shebang + import/source patterns Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

+                let cmd_display = if step.command.len() > 60 {
+                    format!("{}...", &step.command[..57])


+  (
+    flock "${__ARGSH_TRACE_LOCK}"
+    printf 'TRACE_EXIT\t%d\n' "$?" > "${__ARGSH_TRACE_FIFO}"
+  )


+source "\$1/args.sh"
+
+# Set an EXIT trap BEFORE sourcing trace.sh
+trap "touch ${_marker}" EXIT


fentas requested a review from Copilot May 10, 2026 10:16

Copilot started reviewing on behalf of fentas May 10, 2026 10:16 View session