docs: add NDJSON event schema specification by thedavidweng · Pull Request #80 · thedavidweng/OpenLoop

thedavidweng · 2026-06-14T23:20:57Z

Summary

Adds docs/specs/event-schema.md formalizing the CLI NDJSON event contract from cli::events module.

Covers:

Envelope format (v, ts, kind)
Lifecycle events (starting, healthy, stopped, failed)
Progress events (with optional pct and detail)
Result events (generation completion)
Error events (with code, recoverable, suggestion)
Generation task events (submitted, queued, running, downloading, completed, cancelled, failed)

Checks off plan item 11.2.1.

Formalizes the CLI NDJSON event contract documented in cli::events into docs/specs/event-schema.md. Covers envelope format, lifecycle, progress, result, error, and generation task event types. Checks off plan item 11.2.1.

greptile-apps · 2026-06-14T23:23:24Z

Greptile Summary

This PR formalizes the CLI NDJSON event contract in docs/specs/event-schema.md and fixes several issues in backend.rs that were flagged in earlier review rounds (pretty-printed JSON, ownership read before operation, double-emit, and backendCode missing from failed-status responses). New integration tests validate the failure-path lifecycle events end-to-end.

docs/specs/event-schema.md now accurately documents the generation task event schema (task_id, variation/total, output_path/duration/format) and explicitly marks the progress/result/error envelopes as "not yet wired", resolving the spec-vs-code mismatches from the prior review.
backend.rs replaces to_string_pretty with compact JSON, reads ownership after each operation, adds a proper lifecycle envelope to all backend subcommands, and ensures backendCode is always included in execute_status output regardless of phase.
cli_contract.rs adds two integration tests that spawn the real binary against an isolated temp directory and assert the NDJSON output and exit code for the backend-code-not-installed failure path.

Confidence Score: 5/5

Safe to merge — the backend.rs changes are correct, the spec accurately documents the current wire format, and the new integration tests exercise the failure path end-to-end.

All previously-flagged issues (ownership timing, pretty-printing, double-emit, backendCode missing from failed-status) are addressed by this diff. The spec explicitly acknowledges which envelopes are not yet wired to CLI commands, removing the spec-vs-code mismatches from the earlier review. The only remaining gap is that the integration tests don't assert the v and ts envelope fields, which would leave a silent regression path — but this does not affect correctness of the shipped behavior.

No files require special attention; the backend.rs logic and spec are consistent.

Important Files Changed

Filename	Overview
docs/specs/event-schema.md	New spec file; correctly documents the current implementation state including bare-JSON generation task events (no envelope), accurate field names, and explicit "not yet wired" callouts for progress/result/error envelopes.
src-tauri/src/cli/backend.rs	Fixes previously flagged issues: ownership is now read after each operation, compact JSON replaces pretty-printing, backendCode is included for all phases in execute_status.
src-tauri/tests/cli_contract.rs	Adds two integration tests exercising the backend start/restart failure path; correctly isolates the DB with a temp HOME. The tests only cover the failure case, and envelope fields (v, ts) are not asserted.
docs/plans/2026-05-14-v1-readiness-master-plan.md	Task 11.2.1 checked off with a brief note on what was delivered. Trivial bookkeeping change.

_{Reviews (21): Last reviewed commit: "docs: clarify planned result event field..." | Re-trigger Greptile}

thedavidweng · 2026-06-14T23:39:00Z

@greptile-ai re-review

- Remove envelope-based lifecycle/progress/result/error sections (emit_* functions have no call sites in CLI code) - Document openloop run, pull, status, enhance JSON output - Note failed event gap and completed event suppression - Move envelope format to 'Defined but Unused' informational section

…vents" This reverts commit 79f3e2f.

- backend status/start/stop/restart: emit lifecycle events in JSON mode - run: emit error events for validation failures in JSON mode The envelope-based event functions (emit_lifecycle, emit_progress, emit_result, emit_error) now have actual call sites in CLI commands.

… wired

Backend status/start/stop/restart --json now emits one NDJSON line with lifecycle envelope fields (v, ts, kind, phase, message) merged into the status object. Previously emitted two outputs: a lifecycle event followed by pretty-printed JSON, breaking NDJSON parsers.

…op/restart

…n absent) - Remove serde_json::to_value(&status) which leaked serde-tagged state field alongside phase, causing potential contradictions - Use serde_json::json!() to construct clean lifecycle objects - port is always present: integer for Healthy, null otherwise - status field no longer leaks into lifecycle output

emit_error() + return Err() caused double stderr: NDJSON error line then human-format error from mod.rs::run(). Let mod.rs handle errors.

- Result Events: restore envelope format (not yet wired), point to Generation Task Events for current bare JSON behavior - Progress/Result/Error: add notes that envelope formats are defined but not yet wired to CLI commands - Notes: clarify only lifecycle events use envelope format today

thedavidweng · 2026-06-15T02:53:05Z

@greptile re-review the latest commit

thedavidweng · 2026-06-15T03:21:25Z

@greptile re-review the latest commit

thedavidweng · 2026-06-15T03:30:39Z

@greptile re-review the latest commit

thedavidweng · 2026-06-15T03:31:49Z

@greptile re-review the latest commit

docs: add NDJSON event schema specification

88fb9d6

Formalizes the CLI NDJSON event contract documented in cli::events into docs/specs/event-schema.md. Covers envelope format, lifecycle, progress, result, error, and generation task event types. Checks off plan item 11.2.1.

greptile-apps Bot reviewed Jun 14, 2026

View reviewed changes

Comment thread docs/specs/event-schema.md

Comment thread docs/specs/event-schema.md Outdated

Comment thread docs/specs/event-schema.md Outdated

Comment thread docs/specs/event-schema.md Outdated

thedavidweng added 2 commits June 14, 2026 16:28

fix: correct field names in event schema to match actual CLI output

6f06395

chore: trigger Greptile re-review

c7cda3f

chore: trigger Greptile re-review

e4154f5

greptile-apps Bot reviewed Jun 14, 2026

View reviewed changes

Comment thread docs/specs/event-schema.md Outdated

greptile-apps Bot reviewed Jun 14, 2026

View reviewed changes

Comment thread docs/specs/event-schema.md

thedavidweng added 9 commits June 14, 2026 16:47

fix: note that failed event is human-mode only in current implementation

efd74b4

chore: trigger Greptile re-review for failed event fix

102ac06

Revert "fix: rewrite event schema to document only actually-emitted e…

eb56d21

…vents" This reverts commit 79f3e2f.

docs: update event schema notes to reflect lifecycle/error events now…

041447b

… wired

style: cargo fmt

e43b2c0

fix: remove needless borrow in emit_lifecycle call

b712757

greptile-apps Bot reviewed Jun 15, 2026

View reviewed changes

Comment thread src-tauri/src/cli/backend.rs Outdated

thedavidweng added 4 commits June 14, 2026 17:45

style: cargo fmt

9dd0df3

fix: use backend.ownership() instead of hardcoded 'owned' in start/st…

717ba57

…op/restart

fix: use to_string instead of to_string_pretty in execute_logs

c2f297e

greptile-apps Bot reviewed Jun 15, 2026

View reviewed changes

Comment thread src-tauri/src/cli/backend.rs Outdated

fix: read ownership after start()/restart() to capture correct state

3014d23

greptile-apps Bot reviewed Jun 15, 2026

View reviewed changes

Comment thread src-tauri/src/cli/run.rs Outdated

fix: remove emit_error from run.rs to avoid double stderr output

058a468

emit_error() + return Err() caused double stderr: NDJSON error line then human-format error from mod.rs::run(). Let mod.rs handle errors.

greptile-apps Bot reviewed Jun 15, 2026

View reviewed changes

Comment thread src-tauri/src/cli/backend.rs Outdated

thedavidweng added 2 commits June 14, 2026 19:13

fix: include backendCode in failed-status lifecycle response

3476aa0

fix: align backend lifecycle JSON failures

7dc7dd6

fix: complete backend lifecycle JSON contract

5b5c6a6

docs: clarify planned result event field changes

f0da4bf

thedavidweng merged commit ae3e027 into main Jun 15, 2026
10 checks passed

thedavidweng deleted the docs/event-schema-doc branch June 15, 2026 03:41

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add NDJSON event schema specification#80

docs: add NDJSON event schema specification#80
thedavidweng merged 24 commits into
mainfrom
docs/event-schema-doc

thedavidweng commented Jun 14, 2026

Uh oh!

greptile-apps Bot commented Jun 14, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

thedavidweng commented Jun 14, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

thedavidweng commented Jun 15, 2026

Uh oh!

thedavidweng commented Jun 15, 2026

Uh oh!

thedavidweng commented Jun 15, 2026

Uh oh!

thedavidweng commented Jun 15, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

thedavidweng commented Jun 14, 2026

Summary

Uh oh!

greptile-apps Bot commented Jun 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

thedavidweng commented Jun 14, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

thedavidweng commented Jun 15, 2026

Uh oh!

thedavidweng commented Jun 15, 2026

Uh oh!

thedavidweng commented Jun 15, 2026

Uh oh!

thedavidweng commented Jun 15, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

greptile-apps Bot commented Jun 14, 2026 •

edited

Loading