Repository navigation
Improve CLI operator reports and agent contracts - #142
Merged
Merged
Conversation
Changes: - Preflight the selected encoder for every command before remote or local work. - Preserve existing context safeguards and document the OTP 26 JSON boundary. Validation: - Passed 94 observer_cli_escriptize_test EUnit tests on OTP 29. - Compiled and passed the encoder-preflight regression on an isolated OTP 26 VM. - Passed rebar3 fmt --check and git diff --check.
Changes: - Distinguish incomplete required evidence from optional probe failures in quick and observation summaries. - Report retained findings accurately for partial captures and document their meaning. Validation: - Passed 26 observer_cli_diagnostic_test EUnit tests, including required-gap and optional-failure regressions. - Passed rebar3 fmt --check and git diff --check.
Changes: - Reject orphan cookie-source and name-mode options rather than silently discarding them. - Explain explicit-target selection and saved-context updates in errors and documentation. Validation: - Passed 45 observer_cli_cli_test EUnit tests, including orphan-option and explicit-target cases. - Passed rebar3 fmt --check and git diff --check.
Changes: - Use the pre-command null identity when a trace action cannot be recognized. - Retain specific identities for recognized trace call and stop actions. Validation: - Passed observer_cli_escriptize_test and observer_cli_schema_test: 97 EUnit tests. - Verified malformed trace actions produce parseable error envelopes with null command identity. - Passed rebar3 fmt --check and git diff --check.
Changes: - Serialize new saved selectors with UTF-8 context version 2 and retain legacy Latin-1 version 1 decoding. - Bound serialized context size and convert persistence/encoding exceptions into controlled errors. - Document downgrade recovery without persisting cookie values. Validation: - Passed 46 observer_cli_cli_test EUnit tests, including Unicode file/env round trips and legacy decoding. - Verified malformed Unicode returns an error instead of escaping as an escript exception. - Passed rebar3 fmt --check and git diff --check.
Changes: - Display log outcomes and byte/line truncation metadata before untrusted log content. - Preserve control escaping, physical-line prefixes, and complete versus partial semantics. Validation: - Passed 87 CLI and log EUnit tests, including byte-cap and line-cap visibility regressions. - Passed rebar3 fmt --check and git diff --check.
Changes: - Centralize public command spelling for text and error recovery hints. - Generate working supervision-tree and trace help commands instead of exposing internal atom names. Validation: - Passed 143 CLI/escript EUnit tests, including help execution for every command identity. - Passed rebar3 fmt --check and git diff --check.
Changes: - Use a null payload when checking output capability so specialized log renderers cannot require capture data before execution. - Exercise text and term preflight across remote, local-context, and log commands. Validation: - Passed the focused all-command encoder-preflight EUnit regression. - Passed rebar3 fmt --check and git diff --check.
Changes: - Render outcome-first compact diagnostic, memory, resource, trace, and distribution reports. - Add text-only --verbose while preserving complete JSON/term evidence and specialized log/context output. - Preserve full actionable identifiers, metric units, partial coverage, and terminal-control escaping. Validation: - Passed 159 CLI, escript, and report EUnit tests; reran all 15 report tests after final refinements. - Built the escript and exercised an isolated OTP 29 target: memory 21 lines, three processes 22 lines, diagnose 25 lines; verbose memory retained 134 lines. - Exercised 80/120-column rendering, Unicode, unavailable metrics, and redirected output. - Passed rebar3 fmt --check and git diff --check.
Changes: - Include rejected parameter values and applicable constraints while preserving public reason codes and exit statuses. - Capture effective target selectors once for connection recovery hints without disclosing cookie contents or weakening redaction. - Explain why reducing output limits does not bypass resource-count admission budgets. Validation: - Passed 148 CLI and escript EUnit tests, including isolated context replacement, unreachable target, credential errors, and redaction regressions. - Passed rebar3 fmt --check and git diff --check.
Changes: - State evaluated rule scope, completed probes, nonrecursive supervision, and the limits of no-findings reports. - Correct scheduler documentation to describe per-process registration cleanup rather than changing other tools' registrations. Validation: - Passed 117 selected escript/report/scheduler-regression EUnit tests. - Verified on OTP 26, 27, 28, and 29 that releasing a child measurement registration preserves the parent's measurement. - Passed rebar3 fmt --check and git diff --check.
Changes: - Encode known Unicode cookie paths and environment names directly in public context metadata and recovery hints. - Preserve raw-byte normalization for unrelated diagnostic values. Validation: - Passed the focused Unicode selector metadata regression for accented, Chinese, and invalid Unicode values. - Passed rebar3 fmt --check and git diff --check.
Changes: - Derive optional, allowlisted next actions on the controller after diagnostic evidence validation. - Preserve legacy target wire payloads and existing recommendation strings. - Require explicit original target binding, exclude credentials and invasive actions, and render safely quoted operator examples. Validation: - Passed 146 actions, diagnostic, escript, and report EUnit tests. - Verified all suggested argv parse, duplicate findings deduplicate actions, and tampered or unrelated actions are rejected. - Passed rebar3 fmt --check and git diff --check.
Changes: - Define command-specific payload fields, findings/evidence, unavailable states, and trace/log completion shapes in the normative v1 schema. - Add pinned development-only Draft 2020-12 validation with emitted fixtures and deliberate malformed variants. - Check exact bundled schema equality in Rebar and Mix CI without adding runtime dependencies. Validation: - Passed both schema EUnit tests and the schema's Draft 2020-12 self-validation. - Validated 102 emitted response fixtures and rejected 1348 negative cases. - Built and verified the Rebar escript's packaged schema; final local Mix packaging verification remains scheduled with full validation. - Passed rebar3 fmt --check and git diff --check.
Changes: - Express context version validation with consistent short-circuit guard operators. - Preserve Unicode and legacy selector decoding behavior. Validation: - Passed the Unicode and legacy context round-trip EUnit regression. - Passed rebar3 fmt --check and git diff --check; the earlier Elvis guard warning is addressed without disabling the rule.
Changes: - Describe public short/long name-mode values rather than internal Erlang shortnames/longnames atoms. - Add a schema regression for actual context selector spelling. Validation: - Validated three real connect/status JSON responses and rejected their negative mutations. - Passed the focused context schema EUnit check, rebar3 fmt --check, and git diff --check.
Changes: - Add local describe commands and direct bundled JSON Schema export without target/context access. - Share command names, option spellings, and sort values between parsing and a typed capability catalog. - Describe machine-readable dependencies, timeout margins, identifier policies, risks, and authorization requirements. Validation: - Passed 166 catalog, CLI, escript, and schema EUnit tests. - Completed the isolated real-escript agent workflow and validated its 18 JSON responses with 119 rejected negative mutations. - Rebuilt and verified the packaged schema, and passed rebar3 fmt --check and git diff --check. - The agent workflow harness will be committed with its dedicated workflow item.
Changes: - Add trusted follow-up and redacted-sharing workflows with explicit target binding and private report handling. - Explain response-local aliases, PID lifetime limits, untrusted logs, and non-executing action proposals. - Register the guide in generated documentation and README navigation. Validation: - Passed four identifier/action EUnit tests covering within-response correlation and cross-response alias reuse. - Built ExDoc documentation without warnings. - Passed rebar3 fmt --check and git diff --check.
Changes: - Add isolated real-escript acceptance with owned nodes, EPMD, cookies, logs, deadlines, cleanup, and schema-ready fixtures. - Run agent workflows for Rebar and Mix in CI and document explicit target binding, conservative concurrency, and bounded retry policies. - Record the CLI changes without introducing a daemon, shared limiter, TUI changes, or a release. Validation: - Passed the complete OTP 29 agent workflow; validated 18 emitted envelopes and rejected 119 negative mutations. - Passed isolated OTP 26 compatibility checks and OTP 26-controller/OTP 29-target text/term checks; rejected JSON trace left sentinel tracing and connection count unchanged. - Built ExDoc, compiled Python test tools, and passed rebar3 fmt --check and git diff --check.
Changes: - Align offline rate metadata with recon's stop-on-burst behavior, including retained trip events. - Keep rate bounds unchanged and avoid promising pacing or an N-event capture limit. Validation: - Passed 11 catalog EUnit tests, including the rate-semantics regression. - Passed rebar3 fmt --check and git diff --check.
Changes: - Update the snapshot integration test for the intentional outcome-first compact header. - Retain the legacy detailed-header assertion through --verbose and check completed-probe visibility. Validation: - Passed the focused snapshot text/term integration test. - The first full suite found this outdated header expectation (860 tests, one failure); full validation is being rerun. - Passed rebar3 fmt --check and git diff --check.
Changes: - Replace shared primitive annotations with property-local units for counts, bytes, bits, seconds, deltas, rates, and opaque scheduler counters. - Preserve all validation keywords and data acceptance conditions while removing guessed raw OTP GC units. - Add unconditional schema-unit checks and 14 deliberate unit-corruption regressions. Validation: - Validated 102 producer fixtures and rejected 1348 payload mutations. - Validated 18 real CLI envelopes and rejected 119 payload mutations; both runs rejected 14 schema-unit mutations. - Verified descriptions are the only schema keyword changes and passed formatting/diff checks.
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #142 +/- ##
==========================================
- Coverage 97.81% 97.65% -0.17%
==========================================
Files 24 27 +3
Lines 8064 8452 +388
==========================================
+ Hits 7888 8254 +366
- Misses 176 198 +22 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Improve the noninteractive CLI for human operators and agents without changing TUI behavior, target protocol 1, authorization boundaries, or runtime dependencies.
--verboseand JSON/term output.describe, bundled schema export, typed response contracts, and controller-derived next-action proposals.Requested implementation sequence
Each requested item has its own commit. Follow-up findings remain separate commits; no squash or history rewrite was used.
65fbd68e18ae1cdf78dd1270d1440bd6a9f1dd23e2cc393fbbf5822d7e42f77dc7ec8d8479564a55a4a31dfd767332727d4d3ec7bSeparate follow-ups fix payload-independent preflight, Unicode public metadata, context guards/name-mode schema spelling, trace burst-breaker terminology, the updated compact snapshot regression, and schema-unit annotation drift.
Public interface and compatibility
observer_cli.cli/v1envelope and existing exit codes.--verboseis text-only; JSON/term already contain full evidence.describe [COMMAND [SUBCOMMAND]]is offline and does not access target credentials or saved context.describe --schema --jsonexports the bundled JSON Schema directly, not an envelope.data.next_actionsis optional and derived on the controller after evidence validation. The target diagnostic wire payload is unchanged. Proposed argv contain no credentials, invasive commands, or implicit saved-context fallback.connect.Validation
Local OTP 29.1.1 and Elixir 1.20.4:
rebar3 as ci check: compile, lint, formatting, xref, Dialyzer and documentation passed.rebar3 eunit: 860 tests, 0 failures.rebar3 as test do eunit, covertool generate: 860 tests, 0 failures; local line coverage 8250/8452 (97.6% rounded). Existing Codecov gates are unchanged.rebar3 fmt --checkandgit diff --checkpassed.Cross-OTP acceptance:
-Werrorin an isolated temporary archive.All live tests used owned temporary nodes, private EPMD/configuration/cookies/logs, and bounded cleanup. No production node was used. A stale compact-header test found by the first full run was corrected with both compact and verbose assertions; the full suite then passed twice. Final review also caught and corrected schema-unit descriptions, which now have explicit regression guards.
Scope boundaries
No TUI redesign, resource filters, multi-profile contexts, general target-wide limiter, production load test, MCP/daemon, tag, Hex publication, or merge. Hosted CI and review approval remain separate from the local evidence above.
Hosted CI result
CI run 36437133165 passed for OTP 26, 27, 28, 29 and the OTP 29 / Elixir 1.20 / Mix job. Both
codecov/patchandcodecov/projectchecks passed. The tag-only release job was skipped as expected.This is a non-draft, open PR awaiting human review approval. It has not been merged or released.