Skip to content

feat(cli)!: replace moq ls with follow-only moq announced - #4877

Merged
kixelated merged 4 commits into
mainfrom
quest/m1/cli-announced
Oct 6, 2026
Merged

kixelated merged 4 commits into
mainfrom
quest/m1/cli-announced

Conversation

@kixelated

@kixelated kixelated commented Oct 5, 2026 •

Copy link
Copy Markdown
Collaborator

Quest: quest/m1/cli-announced.md (deleted here as complete).

Problem

moq ls one-shot mode and network shell completion are the only readers of the announce Live marker, which Delete the live marker removes because an origin fed by many sessions cannot honestly answer "caught up".

Approach

  • moq ls becomes moq announced [prefix] [--json], follow-only, until interrupted. Exits non-zero when the session ends.
    • Terminal, no --json: redraws the announced set in place (cursor-up and erase, autowrap off while drawing so long paths cannot break the line count). A set taller than the terminal shows what fits and ends in (N more), since cursor-up cannot reach lines that scrolled away; the height comes from terminal_size, read per frame.
    • Piped: + path / - path lines, byte-for-byte what ls --follow printed. --json prints the same {"path", "active"} objects.
  • Shell completion is local-only. Deleted the BROADCAST, VIDEO_NAME, and AUDIO_NAME completers plus everything that only let them dial: the thread-local globals, MoqSide::from_argv, args::Environment, the partial-arg readers, and the moq-msf dev-dependency. Capture-device completers stay.
  • Nothing in rs/moq-cli reads AnnounceEvent::Live any more. announce-live-removal loses its Required entry and is now unblocked.
  • Docs updated: doc/bin/cli.md, doc/bin/inspect.md, doc/bin/relay/http.md. doc/concept/moq-lite.md only mentions Unix ls (dotfiles), so it is unchanged.

Tests: the existing relay-backed tests now cover the event lines, JSON, and session loss. New tests cover the redraw frames, overflow and shrink on a vt100 virtual terminal, ls and --follow being refused, and completion not dialing even when a reachable relay is on the line. The env-vs-reject test moved to args.rs. just check passes.

Impact

  • CLI (breaking): moq ls is an unknown command, with no alias. moq announced replaces it, and --follow is gone because following is now the only mode. Scripts only need to change ls --follow to announced.
  • CLI: tab completion no longer suggests relay broadcasts or catalog rendition names.
  • Public library API: none. Wire: none.
  • Dependencies: terminal_size (moq-cli), vt100 (moq-cli dev). moq-msf dev-dependency removed.

Alternatives

  • Keep a one-shot mode with a timeout: rejected by the quest, since it guesses where Live was exact.
  • A TUI crate for the view: not needed. The redraw takes about ten lines.

Decisions

  • The live view draws nothing while nothing is announced: no header and no "none" line. With Live gone it can briefly show an empty or partial list while the initial set arrives.
  • Escaping control characters in printed paths is a follow-up, not this PR.
  • A set taller than the terminal is cut to fit with a (N more) line rather than scrolled or paged (from the Codex review).

Follow-ups

  • Paths are written raw, so a publisher-chosen path with control characters could inject terminal escapes into the live view (old ls had the same issue). Escape non-printables in View.

(Written by Claude Opus 5.5)

🤖 Generated with Claude Code

kixelated and others added 2 commits October 5, 2026 15:54
`moq announced [prefix]` follows announcements until interrupted. On a
terminal it redraws the announced set in place; piped it prints the same
`+ path` / `- path` lines as `ls --follow`, and `--json` the same
`{"path", "active"}` objects. `moq ls`, its one-shot mode, and `--follow`
are gone.

Shell completion is local-only: the `--broadcast`, `--video-name`, and
`--audio-name` completers no longer dial a relay or read a catalog, and the
plumbing that existed only to let them dial goes with them. Nothing in
moq-cli reads the announce `Live` marker any more, which unblocks
quest/m1/announce-live-removal.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated

Copy link
Copy Markdown
Collaborator Author

Outcome: the quest is implemented in full and just check passes locally. Leaving this as a draft for the maintainer.

Open decisions (recommendation first):

  1. The live view prints nothing while the set is empty. Recommend keeping it that way rather than adding a header or placeholder line.
  2. Escaping control characters in paths for the terminal view. Recommend a small follow-up instead of doing it here, since ls had the same exposure.

(Written by Claude Opus 5.5)

@kixelated
kixelated marked this pull request as ready for review October 5, 2026 23:22
@coderabbitai

coderabbitai Bot commented Oct 5, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 35 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 4 included reviews currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration
  • Configuration used: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 2a58851b-f0c0-4a80-ba14-7abca812303a
📥 Commits

Reviewing files that changed from the base of the PR and between 23e9b4d and 35cc83c.

⛔ Files ignored due to path filters (1)
  • Cargo.lock is excluded by !**/*.lock
📒 Files selected for processing (13)
  • doc/bin/cli.md
  • doc/bin/inspect.md
  • doc/bin/relay/http.md
  • quest/m0/broadcast-epoch/hop-removal.md
  • quest/m1/README.md
  • quest/m1/announce-live-removal.md
  • quest/m1/cli-announced.md
  • rs/moq-cli/Cargo.toml
  • rs/moq-cli/src/announced.rs
  • rs/moq-cli/src/args.rs
  • rs/moq-cli/src/complete.rs
  • rs/moq-cli/src/ls.rs
  • rs/moq-cli/src/main.rs
  • Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

Cursor-up cannot reach a line that scrolled off the top, so a set taller
than the terminal pushed stale copies into scrollback and showed only its
tail. Draw what fits and end in a count of the rest.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@kixelated kixelated left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automated review of 5e5b0a6239e14317f4c0c3f317e9a1ebf8f6ea2e (Codex adversarial review plus a read-through)

Verdict: one real finding, fixed in cc4918da3. No design concerns.

  • [medium] The live view overflowed the terminal (Codex). View moved up by the whole set's line count, but cursor-up stops at the top of the screen. Once the set was taller than the terminal, each redraw pushed stale copies into scrollback and only the tail stayed visible. Reproduced with a vt100 virtual terminal: 6 paths on a 4-row screen showed c d e. Fixed by drawing what fits (one row is kept for the cursor) and ending in (N more). The height is read per frame via terminal_size, so a resize applies on the next change. The new the_view_fits_the_terminal test plays the frames on vt100, including a shrink. doc/bin/cli.md mentions the count.
  • Read-through: the ls and --follow removals are complete; no moq ls invocation remains in docs, recipes, or demos. Event::Live and Update fall through _ => continue, so announce-live-removal can delete the variant without touching the CLI. The connection-closed branch is checked first, so a closing session's retractions are not printed as - path lines. Completion no longer dials, and completion_never_dials proves it against a live listener.
  • Not addressed, already a recorded follow-up: paths are printed raw, so control characters in a publisher-chosen path reach the terminal.

(Written by Claude Opus 5.5)

@kixelated
kixelated enabled auto-merge (squash) October 6, 2026 01:28
@kixelated

Copy link
Copy Markdown
Collaborator Author

Grok review of cc4918da35bbc644622274757302164551c77ea5 (full review; first Grok pass on this PR)

moq ls becomes follow-only moq announced, with an in-place view on a terminal and +/- or JSON lines when piped. Shell completion stops dialing the relay. The change is clean. The terminal-height fix in cc4918da is correct: fits = rows - 1 reserves the cursor row, and the vt100 test covers growth, removal, and shrink. ls was added in #4032 and isn't in moq-cli-v0.14.1, so dropping it with no alias or upgrade.md row is fine.

Blocking

None.

Non-blocking

  1. Anything else written to the terminal breaks the redraw (rs/moq-cli/src/announced.rs:144-147). View assumes the only output since the last frame is its own drawn lines. Logs go to stderr, which is usually the same tty, at info by default, and doc/bin/cli.md itself suggests RUST_LOG=debug. One log line between frames moves the cursor down a row. The next \x1b[{drawn}F then lands one line too low, so the top path of the old frame stays on screen as a stale duplicate, and the log line is erased. Under -v or RUST_LOG=debug this happens on every change. Possible fixes: draw the view on the alternate screen and repaint from home (\x1b[H\x1b[J) each frame, which doesn't care about interleaved output, or raise the default log level to warn when the view is active. At minimum, mention it in the docs.
  2. The session-end test doesn't check the claim it relies on (announced.rs:83-89, test fails_when_the_session_ends). The biased select assumes the retraction of every route on close is never printed. Nothing asserts that, so a teardown that delivers Ends before closed() resolves would print a - path for every broadcast before the error, and scripts would read those as real ends. The old --follow had the same code, but this is now the only mode. After expect_err, assert that lines.next_line() gives None (the writer has dropped), so that no - other/c slipped out.
  3. Nit: with rows == 1, fits is 0 and the frame is (N more)\n, which takes 2 rows, so every change scrolls and the stale-scrollback problem comes back. Clamping with rows.max(2) or skipping the draw avoids it.

CI

Every job was still queued when I checked, so this assumes it goes green.

Verdict: MERGE (once CI is green)

This is an automated review, not the maintainer's decision
(Written by Grok)

@kixelated
kixelated merged commit 44142c2 into main Oct 6, 2026
12 of 14 checks passed
@kixelated
kixelated deleted the quest/m1/cli-announced branch October 6, 2026 02:23
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