cli-preference: jaq is not a drop-in for jq - #45
Merged
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c586881235
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | `top` / `htop` | `bottom` 🦀 (`btm`) | `references/bottom.md` | Graphs, network, processes | | ||
| | `cd` + history | `zoxide` 🦀 (`z`) | `references/zoxide.md` | Shell init required | | ||
| | `jq` | `jaq` 🦀 | `references/jaq.md` | Faster; near-identical syntax | | ||
| | `jq` | `jaq` 🦀 | `references/jaq.md` | Faster. **Not alias-safe** — no auto-vivification; use `pathfinder` for existing jq scripts | |
There was a problem hiding this comment.
This commit edits the skill source but leaves spacecraft-cli-preference.zip and spacecraft-cli-preference.skill byte-for-byte at their parent versions, so consumers installing either bundle still receive the old alias-safe guidance and incorrect multi-file slurp example instead of these corrections. Rebuild and include both bundles with the source changes.
AGENTS.md reference: AGENTS.md:L95-L98
Useful? React with 👍 / 👎.
The reference's Gotchas said only that "a handful of exotic jq features aren't
supported" and that `--stream` is missing. Measured against jq 1.8.1 that is a
serious understatement, and the page was recommending a command that silently
does the wrong thing.
The substantive gap is auto-vivification: jq creates missing containers along an
assignment path and jaq does not, so `echo null | jaq '.a.b = 1'` errors where
jq returns {"a":{"b":1}}. Every "build the object as you go" idiom breaks.
Example 6 was `jaq -s 'add' a.json b.json`. jaq slurps per file and runs the
filter once per input, so that command prints two results where the reader
plainly expects one. Corrected to a single file with the divergence called out.
Also records: output-format flags are not last-wins under jaq, 22 jq builtins
are missing, 9 jq flags are rejected, and the arithmetic corners. Adds the
warning that jaq has `-i/--in-place` where jq does not, so an unrecognised flag
must never be passed through blindly.
Points at Pathfinder for the case where existing jq scripts have to keep
working, and marks the §3 mapping-table row as not alias-safe.
The SKILL.md frontmatter description is untouched and remains 986 characters,
within the §5.6 cap.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011r8wNFByLqoc2ZWevWUUMu
PR #45 edited spacecraft-cli-preference/SKILL.md and references/jaq.md without rebuilding the two bundles that are the install surface, so every consumer installing from the zip would still get the old "near drop-in" claim and the wrong slurp example. Rebuilt both from the rebased branch, so they also carry the LICENSE file that landed in #47. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01M94JK8t6zguGCTDP7udiUv
UnbreakableMJ
force-pushed
the
fix/jaq-compat-reference
branch
from
August 24, 2026 21:48
c586881 to
c88bdb1
Compare
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.
The
references/jaq.mdGotchas section said only that "a handful of exoticjqfeatures aren't supported" and that--streamis missing. Measured against jq 1.8.1, that is a serious understatement — and the page was recommending a command that silently does the wrong thing.The substantive gap: auto-vivification
jq creates missing containers along an assignment path; jaq does not. Every "build the object as you go" idiom breaks, including
reduce … (null; .[$k] = …).A recommended example that was wrong
Example 6 was
jaq -s 'add' a.json b.json. jaq slurps per file and runs the filter once per input, so that command prints two results where the reader plainly expects one. Corrected to a single file, with the divergence spelled out.Also recorded
jq -c --tabpretty-prints;jaq -c --tabis compact).unknown flag."a" * 0isnull(jq:"");1 / 0isInfinity— invalid JSON on stdout.-i/--in-place, which jq does not. Worth stating explicitly: anything that forwards unrecognised flags to jaq can turn a jq typo into a file rewrite.Pointer
Pathfinder is the shim for keeping existing jq scripts working. The §3 mapping-table row is updated to say jaq is not alias-safe.
The SKILL.md frontmatter
descriptionis untouched and remains 986 characters, within the §5.6 cap.