Add help:OP op and clear error on dual @- stdin clash (#341)#351
Merged
Conversation
Two ergonomics papercuts from one session. help:OP — print a single op's full reference (syntax, uncompacted description, example) from .supertool.json. Op hints pointed at "./supertool help vim" but no help op existed; the front door was dead. Reuses the config as single source of truth, scoped to one op and never compacted. Unknown op errors with a pointer to 'ops'; a real builtin without a config entry says so distinctly. dual @- — two op:@- (stdin) ops in one call both read the single stdin stream; the second got empty input and died with an opaque @file parse error. main() now rejects >1 @- in a pre-pass (sibling to cwd:) naming the offenders and the escape hatches (@file / batch). Tests: 7 for help (test_meta_ops), 6 for the clash (test_stdin_clash_341). Docs: meta.md, input-forms.md, CHANGELOG. Co-Authored-By: Max <noreply>
The guard matched only single-colon op:@-; the triple-colon payload form op:::@- also reads stdin (dispatch splits on ':::'), so two of them bypassed the guard into the same opaque parse error it exists to prevent. Strip leading colons from the value before comparing. Tests for the triple-colon and mixed single/triple forms. Co-Authored-By: Max <noreply>
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.
Context
Closes #341 — three ergonomics papercuts were filed together; this PR fixes the two that need code (the third is doc-only, see below).
1.
help:OPop. Op hints and thevimexample told the reader to "see./supertool help vim", but nohelpop existed —./supertool help vimreturnedunknown operation: help, a dead front door.help:OPprints a single op's syntax, uncompacted description, and example, read straight from.supertool.json(builtin-ops → custom ops → aliases). Config stays the single source of truth — same metadataopslists, but scoped to one op and never compacted, so a long description (vim's ~1.5KB grammar) prints in full instead of being dropped byops-compact's filter. An unknown op errors with a pointer toops; a real built-in with no config entry says "has no documented help" rather than "unknown operation", distinguishing the two. Read-only and parallel-safe; registered in.supertool.jsonsoopslists it andhelp:helpself-documents.2. Dual
@-stdin clash../supertool 'edit:@-' 'edit:@-'made both ops callsys.stdin.read(); the first drained the single stream, so the second read empty and died with@file ... parse error (<stdin>): Expecting value: line 1 column 1— naming neither the cause nor the fix.main()now detects >1op:@-in a pre-pass (sibling to thecwd:pre-pass, before any dispatch) and exitsstdin: only one '@-' op is allowed per call (got N: ...), listing the offenders and pointing at the two escape hatches (@filepath / onebatch:@-ops array). Took the cheap fail-fast over "route multiple stdins through an ops-array" — stdin is one stream, splitting it cleanly would mean inventing a delimiter.3. (not in this PR) gh-issue-create vs mr body-format mismatch. I'd argue this is documentation, not code:
mrtakes positionalPATH|TIME|LABELSandgh-issue-createis a pure TOML payload — unifying the formats adds a sniff-the-input branch with real ambiguity (is line 1 a title ortitle =?). Cheaper and safer to document the divergence in both op hints. Happy to do that in a follow-up if preferred.Changes
supertool.py—op_help()+helpdispatch branch + parallel-safe; dual-@-guard inmain().supertool.json— registerhelpbuiltin-opdocs/operations/meta.md—helprow + discovery patterndocs/input-forms.md— one-@--per-call ruleCHANGELOG.md— Added (help) + Fixed (stdin clash)Tests
tests/test_meta_ops.py— 7 new: full reference render, custom-op/alias lookup, missing-arg error, unknown-op error, known-builtin-without-docs, dispatch route, parallel-safe membershiptests/test_stdin_clash_341.py— 6 new: clash rejected pre-dispatch, offenders named, single@-passes, one-@-+file-payloads passes, zero passes, bare@-arg not flaggedVerified: reproduced both original failures → now clear; targeted regression green (
162 passed@file/batch/parallel/chaos/meta +14 passedstdin/cwd).🤖 Generated by Max — the help op that finally answers its own door.