@k-leumas/queque-cli 0.9.2 → 0.10.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "publishConfig": {
4
4
  "access": "public"
5
5
  },
6
- "version": "0.9.2",
6
+ "version": "0.10.1",
7
7
  "repository": {
8
8
  "type": "git",
9
9
  "url": "git+https://github.com/k-leumas/queque.git"
@@ -0,0 +1,124 @@
1
+ # Writing a shell adapter
2
+
3
+ QueQue's shell layer is one adapter script per shell. The adapter owns everything the shell does differently: the key binding, reading and writing the line, the prompt redraw and the result read. Everything after the trigger, from the picker to the provider, is the unchanged `qq client`, and shared code never names a shell.
4
+
5
+ | Shell | Adapter | Status |
6
+ |---|---|---|
7
+ | zsh | [`zsh/queque.zsh`](zsh/queque.zsh) (ZLE widget) | shipped, the reference adapter |
8
+ | bash | [`bash/queque.bash`](bash/queque.bash) (readline `bind -x`, bash 5.0+) | shipped |
9
+ | fish | `fish/queque.fish` | planned (Phase 12) |
10
+
11
+ This page is the contract a new adapter follows. When in doubt, read the zsh adapter, then the bash one: each section comment there says where and why it differs.
12
+
13
+ ## The contract
14
+
15
+ - One file, `shell/<name>/queque.<ext>`, sourced from the shell's rc file by `qq init`. All of the shell's quirks stay inside it.
16
+ - Non-interactive shells that read the rc file (scp, rsync, `bash -c`) must print nothing and change nothing.
17
+ - A shell version that cannot run the adapter refuses at source time with one line on stderr (bash: `queque: the ?? trigger needs bash 5.0+ (found …)`) and binds nothing. Keep the code above that check parseable by the oldest version you refuse.
18
+ - Call external tools through `command` (or the shell's equivalent), so a user's `alias rm='rm -i'` cannot change what the adapter runs. A user's `set -e` or similar must not leak in or out.
19
+ - The adapter never runs the chosen command. It places it in the line; the user presses Enter (insertion-only).
20
+ - A background job that runs Node (the daemon prewarm `qq daemon --ensure`) gets none of the terminal: redirect stdin, stdout and stderr (`</dev/null >/dev/null 2>&1`). A Node process with the terminal on any of them writes back the terminal settings it saw at startup when it exits, even in the background, so it can undo the picker's raw mode and turn Enter into text in FILTER.
21
+
22
+ ## The trigger
23
+
24
+ - Bind `?` alone, in the insert-style keymaps only (zsh `emacs` and `viins`, bash `emacs` and `vi-insert`, fish default and `insert`). Never the vi command keymap, where `?` searches history.
25
+ - On each `?`, look at the character before the cursor. Not a `?`: insert a literal `?` at once and return. A `?`: remove it, remember the line and the cursor, and start QueQue.
26
+ - Never bind the two-key sequence `??`: a lone `?` would then wait for the key-sequence timeout before it appears.
27
+ - Leave pasted text alone: a pasted `??` must not open the picker. zsh and bash rely on bracketed paste (`qq doctor --shell bash` checks that it is on); fish handles paste internally.
28
+ - Count the cursor in characters, not bytes, so multibyte text needs no special handling.
29
+
30
+ ## The session dir
31
+
32
+ Every trigger gets a private dir from `mktemp -d /tmp/qq-sess.XXXXXX`, then `chmod 700`. An empty or failed `mktemp` stops right there with `queque: cannot create a temp dir in /tmp`: never fall back to a path like `/request.json`. Every exit after the dir exists removes it (see the two-flag cleanup below).
33
+
34
+ ## request.json
35
+
36
+ Written into the session dir with a JSON tool (`jq -n --arg …`, or `jq -Rs .` per value), never by string concatenation. The schema is `shellRequestSchema` in [`src/contracts/shell.ts`](../src/contracts/shell.ts):
37
+
38
+ | Field | Value |
39
+ |---|---|
40
+ | `version` | `1` |
41
+ | `ttyPath` | the terminal, usually `/dev/tty`; the client opens it itself |
42
+ | `cwd` | the shell's working directory (absolute) |
43
+ | `shellPid` | the shell's pid (a number: `--argjson`) |
44
+ | `lbuffer` | the line before the cursor, without the trigger `?` |
45
+ | `rbuffer` | the line after the cursor |
46
+ | `shell` | the shell's name from `SHELL_NAMES`; it defaults to `zsh`, so always send it |
47
+ | `shellVersion` | the raw version string (`$BASH_VERSION`, `$ZSH_VERSION`, fish `$version`), at most 40 characters; telemetry keeps only major.minor |
48
+
49
+ The line travels as two strings, never as a buffer plus a cursor index: Node counts UTF-16 units and shells count characters.
50
+
51
+ Then run `qq client --request-file <dir>/request.json --result-file <file>`, and export `QQ_RESULT_FILE=<file>` to the client first so its crash handlers can still write a cancel. Scope that export to the trigger call (bash and zsh use `local -x`): left in the user's shell it points into a deleted session dir, and any later `qq` that crashes would write there.
52
+
53
+ ## Results
54
+
55
+ The client writes one JSON object, `shellResultSchema` in the same file:
56
+
57
+ | `kind` | Adapter does |
58
+ |---|---|
59
+ | `cancel` | restore the original line and cursor |
60
+ | `replace-buffer` | print the query (dim, `queque › …`) and the command above the prompt, set the line to `lbuffer` + `rbuffer` with the cursor between them |
61
+ | `error` | print `message`, restore the line and cursor |
62
+
63
+ Anything else (no file, unparsable JSON, an unknown kind, an empty `lbuffer`) restores the line and cursor. Print user text through a `%s` argument, never as a format string.
64
+
65
+ **Restore the line and the cursor on every path that does not accept.** zsh gets the cursor back by restoring `LBUFFER` and `RBUFFER`; bash saves `QQ_ORIG_POINT` and sets `READLINE_POINT` back.
66
+
67
+ **History:** add the natural-language query (`lbuffer` before the trigger) to history, never the command. The command enters history only when the user runs it.
68
+
69
+ ## Inline and Zellij paths
70
+
71
+ - **Inline** (no `$ZELLIJ`): run the client as a foreground child; it writes `result.json` in the session dir. If the client crashes and leaves no result, the line is restored and the adapter clears the instant frame itself.
72
+ - **Zellij** (`$ZELLIJ` set): run the client in `zellij run --floating --close-on-exit --name qq`, with the result coming back as one newline-terminated line through a FIFO in the session dir. Export `QQ_PANE_WIDTH` and `QQ_PANE_HEIGHT` (default 80 and 24) for the client.
73
+ - Open the FIFO before the launch, so a pane that never starts cannot block the open.
74
+ - The result read must time out after 30 seconds and count as a cancel, so a dead pane can never hang the shell. In fish, `read -t` means tokenize, not timeout, and `read` has no timeout at all: use a guard process that writes a cancel into the FIFO after 30 seconds.
75
+ - Setup failures are a restore with a fixed debug-log reason, never a silent wait: `mkfifo failed`, `fifo open failed`, and `zellij run failed` (a launcher that exits non-zero writes a sentinel line into the FIFO, which wakes the read at once).
76
+ - Call `zellij` without `command`, so tests can replace it with a shell function.
77
+
78
+ ## Installed-tool handoff
79
+
80
+ Before the client starts, the adapter writes the names the shell can resolve into the session dir, next to request.json (`TOOL_HANDOFF_FILES` in [`src/client/tool-handoff.ts`](../src/client/tool-handoff.ts)):
81
+
82
+ | File | Contents |
83
+ |---|---|
84
+ | `commands.txt` | every command name the shell resolves, `PATH` included |
85
+ | `builtins.txt` | builtins (never flagged as missing) |
86
+ | `functions.txt` | functions without a leading `_`, plus alias names; fish abbreviations (`abbr --list`) go here too |
87
+
88
+ One name per line, unordered. Rescan `PATH` on every trigger so a tool installed a moment ago counts. An empty `commands.txt` means "no handoff": remove all three files. `QQ_TOOL_AWARENESS=0` skips the scan.
89
+
90
+ **Fast scans** (zsh, about 9 ms) write the files before the client starts and need nothing else.
91
+
92
+ **Slow scans** (bash `compgen`, about 85 ms; fish is similar) run in a detached writer alongside client startup, behind the `tools.pending` marker (`TOOL_HANDOFF_PENDING`):
93
+
94
+ 1. The adapter creates `<dir>/tools.pending`, then starts the writer detached and silent (no job-control noise in the user's terminal).
95
+ 2. The writer writes the three files, removes `tools.pending` last, then removes the dir if `closed` exists.
96
+ 3. The client waits up to 500 ms while `tools.pending` exists (`TOOL_HANDOFF_PENDING_BUDGET_MS`), then gives up and shows no flags.
97
+
98
+ **Two-flag cleanup:** at every exit the adapter writes `<dir>/closed`, then removes the dir only if `tools.pending` is gone. Each side sets its own flag before it checks the other's, so whichever finishes last removes the dir, exactly once in effect.
99
+
100
+ ## The instant frame
101
+
102
+ The moment the trigger fires, before `mktemp`, `jq` and Node, the adapter paints the `queque › <lbuffer>` header and a `thinking…` row, so the picker shows something at once. Inline, it paints into the terminal; in Zellij, it writes `instant-frame.txt` into the session dir for the pane wrapper. `QQ_INSTANT_FRAME=0` paints nothing.
103
+
104
+ The bytes are specified once, in [`src/shared/instant-frame-spec.ts`](../src/shared/instant-frame-spec.ts) (`instantFrameRows`, `inlineInstantFrameBytes`, `paneInstantFrameBytes`, `INSTANT_FRAME_SPEC`). A new adapter ports those functions natively (no forks) and adds itself to `ADAPTERS` in [`tests/instant-frame-parity.test.ts`](../tests/instant-frame-parity.test.ts), which compares every adapter with the reference byte for byte.
105
+
106
+ ## Prompt redraw
107
+
108
+ After the picker, every line of a multi-line prompt must come back. Each shell needs its own fix: bash reprints the leading lines of `${PS1@P}` itself, because readline repaints only the last one; fish prints a newline first and pads for the lines of `fish_prompt`, then calls `commandline -f repaint`.
109
+
110
+ ## Checklist for a new shell
111
+
112
+ The shell name is already in `SHELL_NAMES`. To ship it:
113
+
114
+ 1. Write `shell/<name>/queque.<ext>` to this contract.
115
+ 2. [`src/shared/shell-registry.ts`](../src/shared/shell-registry.ts): fill in its `SHELL_SPECS` entry (rc file, adapter file, version probe, floors, binding widget and keymaps) and set `shipped: true`.
116
+ 3. [`src/registry/bootstrap.ts`](../src/registry/bootstrap.ts): `registerShellAdapter({ id, shell, description })`.
117
+ 4. [`src/cli/commands/doctor.ts`](../src/cli/commands/doctor.ts): a binding probe for the shell (bash has `BASH_BINDINGS_SCRIPT` and `parseBashBindings`). The version check reads the registry; the doctor check id already exists in `DOCTOR_CHECK_IDS`.
118
+ 5. [`src/contracts/telemetry.ts`](../src/contracts/telemetry.ts): `SHELL_KINDS` already lists every `SHELL_NAMES` entry; nothing to add unless the name is new.
119
+ 6. [`src/shared/command-words.ts`](../src/shared/command-words.ts): the shell's reserved words in `RES_EXPECT_BY_SHELL` and `RES_LOOP_BY_SHELL` if its syntax differs (fish uses the bash rules until then).
120
+ 7. Tests: a row in `PTY_SHELLS` in [`tests/shell-pty.test.ts`](../tests/shell-pty.test.ts) (the tmux PTY harness, `tests/pty/drive.sh`), a row in `ADAPTERS` in the parity test, adapter unit tests like `tests/bash-widget.test.ts`, and the shipped list in [`tests/shell-names-invariant.test.ts`](../tests/shell-names-invariant.test.ts).
121
+ 8. Packaging: the Homebrew formula installs the adapter into `share/queque/`, and CI installs the shell.
122
+ 9. Docs: [docs/INSTALL.md](../docs/INSTALL.md) and the README install block.
123
+
124
+ Harness variables such as `QQ_TEST_BASH`, `QQ_TEST_ZSH` and `QQ_TEST_RESULT_MODE` are for development only; see [CONTRIBUTING.md](../CONTRIBUTING.md#shell-adapter-tests-pty-harness). A harness that sources an adapter must unset `ZELLIJ`, `ZELLIJ_PANE_ID` and `ZELLIJ_SESSION_NAME` first, or it opens real floating panes in your session.