Skip to content

Feat/non pausing logpoints#3

Merged
burrows99 merged 6 commits into
masterfrom
feat/non-pausing-logpoints
Jun 18, 2026
Merged

Feat/non pausing logpoints#3
burrows99 merged 6 commits into
masterfrom
feat/non-pausing-logpoints

Conversation

@burrows99

Copy link
Copy Markdown
Owner

This pull request updates the documentation and supporting files to reflect a major renaming and simplification of the CLI command structure, replacing the previous dynamic and static subcommands with more intuitive, top-level commands such as run, graph, deps, complexity, and symbols. The changes clarify the native-first philosophy, improve flag and argument consistency, and update all examples, migration guides, and schema references accordingly.

CLI Command Renaming and Unification:

  • Replaced all references to trace-cli dynamic and trace-cli static with trace-cli run, trace-cli graph, trace-cli deps, trace-cli complexity, and trace-cli symbols throughout the documentation, examples, and migration guides. This includes updates to sample commands, envelope JSON output, and migration instructions. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11]

Flag and Argument Consistency:

  • Standardized flag names across documentation: --bp--breakpoint, --expr--expression, --out--output, and --db--database-url for improved clarity and usability. [1] [2] [3]

Native-First Model Clarification:

  • Added a new section to the README explaining the native-first runtime model, emphasizing that the CLI is intended to run directly on the host machine, with Docker Compose reserved for optional collector and UI infrastructure. [1] [2] [3]

Supporting Documentation and Migration Updates:

  • Updated the migration guide and schema documentation to reflect the new command structure and naming conventions, removing references to the old flat interface and clarifying the new entry points. [1] [2] [3] [4] [5]

Sample Usage and Output Updates:

  • Revised all sample commands, Docker instructions, and JSON envelope examples to match the new CLI structure and flag names, ensuring consistency for end users. [1] [2] [3] [4] [5] [6]

These changes modernize the CLI's interface, making it more intuitive and easier to use, while ensuring all documentation and supporting files are up to date with the latest design decisions.

burrows99 and others added 6 commits June 18, 2026 14:56
…he VM

Breakpoints are now armed as logpoints (a conditional breakpoint whose
condition captures state and returns false), so a hit ships its stack +
in-scope locals + exprs out via a Runtime binding without ever pausing
execution. The traced app runs at full speed, hot paths are cheap, and
there is no human-style stop-and-wait — built for an agent that reads the
trace and re-aims breakpoints.

Locals are still captured automatically: ScopeExtractor statically reads
the generated source and lists the in-scope names (function-body scopes,
matching the old local/block/catch filter), which the condition gathers
defensively. --expr adds computed/derived values on top. The call stack
arrives as new Error().stack and is source-mapped via SourceMaps.

The TraceEvent shape is unchanged, so Renderer, lineage, the recording's
trace panel, the collector and the schema are all untouched — Chrome video
recording included.

- new: ScopeExtractor (TS-based in-scope name extraction), Logpoint
  (condition builder + in-page serializer + payload→TraceEvent capturer)
- Tracer/TabTracer: replace the pause→capture→resume loop with
  binding-driven collection; instrumentation pause kept only for binding
  before first-run code
- remove: EventCapturer and the dead pause-queue machinery
  (waitForStop/hasQueued/interrupt, renderRemoteObject, step over/into/out)
- --max-hits default 25/30 → 100 (cheap to raise without per-hit pause cost)

Validated end-to-end against the node-api (plain JS) and react-app
(sourcemapped TS) fixtures: full locals + exprs + stack + lineage, video
intact, no pauses.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Sweep of unused surface left after the logpoint migration:
- remove TraceOptions.url/shot/record and DynamicRequest.record — all
  declared but never read (--url becomes a goto step; recording is gated
  by isChrome, not a flag)
- traceNode: add a safety Debugger.paused→resume so a stray `debugger;`
  in the traced app can't stall the drain loop

Note: the beforeScriptExecution instrumentation pause was evaluated for
removal and kept — it's the bind-before-first-run mechanism, not pause
bloat. Removing it dropped on-mount capture from 3 hits to 0 in the
react-app fixture (logpoint hits never pause regardless).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The bind-before-first-run instrumentation pause was scattered as a bare
`instrument` boolean + a CDP call buried in #onPause, with no signpost —
easy to mistake for leftover pause-tracer code. Make it unmissable:

- rename instrument/instrumentFirst → bindBeforeFirstRun everywhere
  (TabTracer.arm, JourneyRunner #connect/start/#waitNewTab, Tracer)
- extract TabTracer.#armFirstRunBindPause(); rename #instrId → #firstRunPauseId
- one canonical doc block on TabTracer + a greppable "THE ONE PAUSE" marker
  at every touchpoint (incl. README), stating it's bind-only, never on a
  hit, self-dropping, and load-bearing (3→0 on-mount hits without it)

No behavior change — Chrome on-mount still 3 hits, 37 tests pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- Added ShellAnalysisCommand as an abstract base class for running external analysis tools and normalizing their output into a Trace.
- Introduced ToolInvocation and AnalysisOutcome interfaces to standardize tool invocation parameters and results.
- Updated SymbolsCommand to extend ShellAnalysisCommand, encapsulating the logic for invoking tree-sitter and interpreting its output.
- Refactored runTool function to use spawn instead of execFile for better handling of large outputs, capturing stdout and stderr to temporary files.
- Created graphView module for rendering call graphs in both text and HTML formats, separating concerns from GraphCommand.
- Added shared empty/error guard in TraceCommand for consistent rendering of error messages across commands.
…base

- Renamed `sleep` parameter from `ms` to `milliseconds` for clarity.
- Updated command descriptions in trace.schema.json to reflect accurate terminology.
- Changed `Loc` to `SourceLocation` and `col` to `column` in trace.schema.json for consistency.
- Refactored validation.ts to improve variable naming for better readability.
- Updated version.ts to use `moduleDirectory` instead of `here` for clarity.
- Improved S3ArtifactStore.ts by enhancing variable names and error logging.
- Refactored CdpDriver.ts for better parameter naming and error handling.
- Updated ProtocolDriver.ts to use consistent callback naming.
- Adjusted test cases to reflect changes in schema and naming conventions.
- Added output tests for envelope transformations and code registry.
- Updated README and configuration files to reflect command changes from `dynamic` to `run`.
- Enhanced UI components to use updated naming conventions for event attributes.
- Refactored types.ts to improve clarity and consistency in interface definitions.
@burrows99 burrows99 merged commit 9aeb065 into master Jun 18, 2026
1 check passed
@burrows99 burrows99 deleted the feat/non-pausing-logpoints branch June 18, 2026 20:27
burrows99 added a commit that referenced this pull request Jun 18, 2026
…engine)

Re-applies the dashboard/ingestion work on top of the merged non-pausing
logpoint engine (PR #3). Engine-side changes from the original local commit
are dropped as superseded by that rewrite (which already captures console output).

- Ingestion route POST /v1/traces in the standalone Next.js dashboard, with
  validation + error handling.
- OpenTelemetry self-observability (auto-instrumentation: request + error logging).
- `trace serve` launches the standalone Next.js dashboard (UI + same-origin API
  + SSE), backed by Postgres; Collector reduced to the client-side emit() helper.
- Same-origin UI API calls (no base URL); lazy session store; standalone Next
  output with security headers + CSP; OTel deps added.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant