Beagle SCM

BEE-017: bee see <ref>... — print the chunk each reference names

A permalink has no CLI entry point at all. door.js seatOf resolves every reference shape there is — permalink, path, FSEG partial, ticket code, cross-repo — but it is reached ONLY from a pager click and from http, never from argv, so bee LITE-006:Kk:RcNe falls through to the filesystem leg and answers cannot open. Minting permalinks (BEE-016) without a way to read one back from a terminal is half a feature. bee see <ref>... is that half: one hunk per reference, the landed line with a couple of lines of context each way, through the ordinary view/render pipeline so it pages, pipes, colours and serves over http like every other verb.

Input

Context

The gap showed up while checking BEE-016's own output and could not be closed from the CLI.

• bee --plain "LITE-006:Kk:RcNe" answers cannot open LITE-006:Kk:RcNe then BRONONE: no verb matched, so main.js sent it to the fs leg (pathView), which reads the ref as a literal path.
• Verifying that the minted links even worked took bee --eval calling door.openTarget by hand. That is not a thing a reader should have to do.
• gritzko's shape, verbatim: bee see BEE-005:1Jz:mJpI BEE-005:1_Y:mJpI — a LIST of refs, "two lines of context each way, hunks".
• Both of those resolve today through seatOf, to todo/BEE/BEE-005.mkd lines 58 and 73 in ///bee-journal: cross-repo, and far enough apart to be two separate chunks.

Goals

A reference in, the text it names out.

• One hunk per reference, in the order given: see answers what it was asked, and a batch of refs is a batch of hunks.
• Every reference shape seatOf knows, since see adds no resolver of its own — permalink, path, partial, ticket code, pocket page, another registered repo.
• Two lines of context each way by default, -C<n> to change it.
• A miss says BEE-003's words (door.refusal), an ambiguity shows the door's own chooser hunk, and neither stops the rest of the batch.
• It is a VIEW, not a SIDE verb: (arg, opts) -> hunks, so the pager, the three renderers and http all take it for free.

Constraints

• NO second resolver: door.seatOf is the one place a reference resolves (LITE-034:40:Mf's ruling), and see calls it.
• No new hunk shape: index/read.js textHunk plus bare: false, which is the "excerpt wears the band" case render/plain.js already documents.
• ninja && ninja -j20 test in quickjab/build green; every existing leg unmoved.

WIP

Design decisions

• ONE HUNK PER REF, never merged. Two refs landing three lines apart print two overlapping chunks, which is predictable and keeps ref-to-hunk one-to-one; diff-style merging is a nicety that can arrive if the duplication ever annoys, and it would cost the banner its single answer.
• CONTEXT IS 2, not diff's 3. A diff hunk frames a CHANGE and needs room to read the shape of it; see frames ONE LINE somebody pointed at, and five lines is enough to say what it is without burying it.
• THE BANNER IS THE REF WITH ITS PATH EXPANDED (ruled by gritzko, 2026-08-16, over three earlier cuts: seatOf's own spelling, then the ref verbatim, then path-and-ref side by side). The full path the ref landed on, carrying the ref's OWN tail: hunk /home/gritzko/src/bee-journal/todo/BEE/BEE-005.mkd:1_Y:mJpI.
• ONE TOKEN, STILL A REFERENCE — which is why this beats the side-by-side form it replaced: the band clicks in the pager and re-reads through see, while saying both which file answered and which anchor asked. Only the path is substituted; the anchor is never re-spelled, so a permalink stays a permalink and a :line stays a line.
• The path is realpath'd rather than left in seatOf's spelling (relative in the ambient repo, absolute elsewhere), so the band says which repo answered without the reader knowing where they stood.
• THE WINDOW IS TOKENIZED AS A WINDOW, so a chunk cut out of the middle of a block comment may paint oddly. Accepted: the alternative is folding whole files to paint five lines.
• -C<n> IS PARSED BY THE VIEW, not by main.js. modeOf knows three mode flags and nothing else; every other word reaches the view verbatim, which is exactly the door a view-local flag goes through.

TODOs

• test/see/run.sh + test/see/see.js, RED first
• view/see.js: the split, the seat, the window
• door.js: see in VERBS
• README.mkd: the verb line
• the leading-mode-flag bug in main.js wants its own ticket (see Blockers)

Blockers and bummers

• A LEADING MODE FLAG HIDES THE VERB, found while testing this: bee --plain cat x answers cannot open cat, because main.js reads argl[0] for a verb BEFORE the flag scan just below it strips flags from anywhere. So bee --plain see <ref> will not work while bee see --plain <ref> will. Its own bug, its own ticket — not fixed here.
• THE BAND DOES NOT ROUND-TRIP FOR A PERMALINK — BEE-018, found by round-tripping it here. An absolute path carrying a hashlet resolves nowhere, because index/perma.js follow hands it to refSpellings, where a leading / means POCKET PAGE. The same path with a :line anchor reads back fine, and so does the ticket code with the hashlet; it is only the two together that fail. The band is right and the resolver is wrong, so nothing was changed here.

Outcome

BUILT AND GREEN, uncommitted: ///bee carries it in the working tree, no VC op run. ninja && ctest -j20 in quickjab/build is 148/148 — 147 before, plus the new JSRCsee, everything else unmoved. gritzko's own line works: bee see --plain BEE-005:1Jz:mJpI BEE-005:1_Y:mJpI prints two five-line chunks of ///bee-journal's BEE-005 at lines 58 and 73.

• view/see.js is the verb, one module under view/ as the layout requires (README.mkd:13, one module per verb); door.js gains one row in VERBS and nothing else. No resolver and no hunk shape were added.
• test/see/ is 12 shell checks plus 17 in see.js, registering itself as JSRCsee through the test/*/run.sh glob.
• THE BAND took three cuts to settle, and the last one is the ruling: seatOf's own spelling first (relative here, absolute elsewhere), then the ref verbatim, then BOTH — <full path>:<line> <ref>. The path alone hid what the reader typed, the ref alone hid where it went; the mapping needs its two ends. A miss and the chooser still band by the ref alone, having no landing to name.
• A view called as a bare module resolves against the cwd, while door.js vopts fills opts.from in for every CLI and http call — which is why the same ref bands differently through the two paths. The test now pins each through the path that produces it.
• Untested before this and now covered: a ref into another registered repo (a second fixture repo, installed, answered by ticket code across the fan-out).