@k-leumas/queque-cli 0.6.0 → 0.6.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/README.md CHANGED
@@ -16,7 +16,7 @@ Welcome to the **future** –
16
16
  ![QueQue demo](assets/demo.gif)
17
17
 
18
18
  > [!NOTE]
19
- > After install, run `qq init zsh >> ~/.zshrc && source ~/.zshrc` to wire up the `??` keybinding.
19
+ > After install, run `qq init zsh && source ~/.zshrc` to wire up the `??` keybinding. `qq init zsh` adds the QueQue source line to the end of `~/.zshrc` itself, so do not redirect its output into the file.
20
20
 
21
21
 
22
22
  <details>
@@ -25,28 +25,56 @@ Welcome to the **future** –
25
25
  ## Requirements
26
26
 
27
27
  - zsh
28
- - Node.js ≥ 20
28
+ - Node.js 24 or newer
29
29
  - [jq](https://jqlang.github.io/jq/)
30
+ - Claude Code signed in, or an Anthropic API key (see [Authentication](#authentication))
30
31
 
31
32
 
32
33
  ```shell
33
34
  npm install -g @k-leumas/queque-cli
34
- qq init zsh >> ~/.zshrc && source ~/.zshrc
35
+ qq init zsh && source ~/.zshrc
35
36
  ```
36
37
 
37
38
  </details>
38
39
 
39
- ## Expose API Key
40
+ ## Authentication
40
41
 
41
- QueQue resolves `ANTHROPIC_API_KEY` in order:
42
+ QueQue talks to Claude in one of two ways. You only need one.
42
43
 
43
- 1. **Environment variable** — `export ANTHROPIC_API_KEY="sk-ant-..."` in your shell or `.zshrc`
44
- 2. **`.env.local` file** — place a `.env.local` in your project directory (or any parent). QueQue searches upward from the current working directory:
45
- ```shell
46
- ANTHROPIC_API_KEY=sk-ant-...
47
- ```
44
+ **Claude Code login (no API key needed).** If you already use Claude Code, QueQue runs `claude -p` on your existing login whenever no API key is set. Sign in once through Claude Code's `/login`:
48
45
 
49
- The `.env.local` option is useful for project-specific keys or keeping the key out of your shell profile.
46
+ ```shell
47
+ claude /login
48
+ ```
49
+
50
+ On this route QueQue uses whatever account and default model Claude Code is set to; it passes no model flag. `claude -p` runs with its tools disabled and session persistence off, so it only answers the query. If `claude` is not on your `PATH` or is not signed in, `??` shows a message like this one:
51
+
52
+ ```text
53
+ QueQue: Claude is not authenticated. Run `claude /login`, or set ANTHROPIC_API_KEY in the environment or .env.local.
54
+ ```
55
+
56
+ **Anthropic API key.** QueQue looks for `ANTHROPIC_API_KEY` in this order:
57
+
58
+ 1. **Environment variable**: `export ANTHROPIC_API_KEY="sk-ant-..."` in `~/.zshrc`, above the QueQue source line.
59
+ 2. **`.env.local` file**: a line `ANTHROPIC_API_KEY=sk-ant-...`. The background daemon searches upward from the directory it was started in, usually the directory your first terminal opened in, and reads the file once. A `~/.env.local` is found from any start directory inside your home directory.
60
+
61
+ An empty or whitespace-only value counts as unset.
62
+
63
+ **Which route wins.** A non-empty `ANTHROPIC_API_KEY` always wins: QueQue calls Claude through the Anthropic SDK and never runs `claude -p`. There is no automatic fallback in either direction. If the API-key request fails, QueQue shows that error instead of trying your Claude Code login, and a failed `claude -p` run never falls back to a key. To switch to your Claude Code login, remove the key from your environment and `.env.local`, then restart the daemon.
64
+
65
+ `QQ_MODEL` picks the model on the API-key route only. The default is `claude-sonnet-5`.
66
+
67
+ ### After changing your key or settings
68
+
69
+ A background daemon answers `??` for every terminal. It starts with your first interactive shell (and again on the next `??` if it is not running) and inherits that shell's environment. It reads `ANTHROPIC_API_KEY`, `QQ_MODEL`, `.env.local` and `~/.config/qq/config.json` once, when it starts.
70
+
71
+ - Put your `export` lines in `~/.zshrc` above the `# queque shell integration` block that `qq init zsh` appended, so the daemon started during shell startup sees them.
72
+ - After changing any of them, restart the daemon from a shell that has the new values:
73
+
74
+ ```shell
75
+ pkill -f 'daemon --socket /tmp/qq-'
76
+ qq daemon --ensure
77
+ ```
50
78
 
51
79
  ## Usage
52
80
 
@@ -58,9 +86,17 @@ find docker containers using port 3000??
58
86
  git undo last commit but keep changes??
59
87
  ```
60
88
 
61
- A selection UI opens in-terminal. Pick a command with arrow keys or fuzzy search, press `Enter`, and the command lands in your buffer — ready to run or edit before you commit.
89
+ A selection UI opens in-terminal. Rows stream in as Claude answers, and you can pick one before the rest have arrived. What you typed stays in the dim `queque ›` header, and the FILTER box opens empty: type to narrow the list, even while `thinking…` is still showing. Move with the arrow keys and press `Enter`. The command lands in your buffer exactly as shown, ready to run or edit. QueQue never runs it for you.
90
+
91
+ Press `Esc` to cancel. It stops the request to Claude and restores what you were typing, so you can tweak your intent and hit `??` again.
92
+
93
+ A command that matches a destructive pattern (`rm`, `sudo` and similar) is marked `⚠ review carefully — this command may be destructive`. The mark is a warning only; the row stays selectable.
94
+
95
+ ### Installed-tool awareness
96
+
97
+ QueQue checks each suggestion against the commands zsh can find on your machine. A row that needs a tool zsh cannot find gets `ⓘ` before its explanation, and the legend reads `ⓘ not installed`. The row stays selectable. When QueQue knows how to install that tool with brew, apt, dnf or pacman, the legend adds `tab prepends the install command`: press `Tab` (or `Shift+Tab`) on the row to switch it to the install form, and again to switch back. The install form is inserted like any other command, never run.
62
98
 
63
- Press `Esc` to cancel and return to what you were typing, you can even tweak your intent and hit `??` again.
99
+ Set `QQ_TOOL_AWARENESS=0` in your shell to turn this off.
64
100
 
65
101
  ### Inside Zellij
66
102
 
@@ -74,18 +110,20 @@ Without Zellij, QueQue falls back to an inline TUI in your current terminal sess
74
110
 
75
111
  QueQue is **insertion-only**: it writes commands into your shell buffer — you press Enter to run them. QueQue never auto-executes suggestions.
76
112
 
77
- **What leaves your machine (when using Claude):**
113
+ **What leaves your machine.** Both routes (`claude -p` and the API key) send the same prompt to Claude:
78
114
 
79
115
  - Your query text and current working directory
116
+ - Your OS platform name (for example `darwin` or `linux`) and shell name (`zsh`)
80
117
  - Git metadata (branch, dirty flag, changed file *names* — not file contents)
81
118
  - Parsed filename hints from your query (no disk reads)
119
+ - The names of installed tools that appear in QueQue's public tool catalog. Your full `PATH` inventory, functions and aliases stay on your machine. `QQ_TOOL_AWARENESS=0` stops even the catalog names.
82
120
 
83
121
  **What QueQue never sends:**
84
122
 
85
123
  - File contents (unless you explicitly opt in later with `QQ_ALLOW_FILE_READ=1`)
86
124
  - Paths matching sensitive patterns (`.env`, credentials, `.pem`, `id_rsa`, etc.) are stripped from git context
87
125
 
88
- **Debug logging:** Off by default. When enabled, logs redact shell buffer text unless `QQ_DEBUG_VERBOSE=1`.
126
+ **Debug logging:** The client and daemon append short diagnostics to `/tmp/qq-<uid>-debug.log`, or to the file named by `QQ_DEBUG_LOG_FILE`. Shell buffer and query text are redacted unless `QQ_DEBUG_VERBOSE=1`. The zsh widget adds its own lines only when `QQ_DEBUG_LOG_FILE` is set. The log stays on your machine.
89
127
 
90
128
  **User config:** Copy [docs/config.example.json](docs/config.example.json) to `~/.config/qq/config.json` to add extra sensitive path patterns, log redaction keys, or destructive-command warnings. Built-in defaults always apply — your patterns are merged on top. Override the file path with `QQ_CONFIG_FILE`. Malformed `config.json` is ignored with a warning; QueQue falls back to built-in defaults (fail-closed).
91
129
 
@@ -97,13 +135,13 @@ Copy [docs/config.example.json](docs/config.example.json) to `~/.config/qq/confi
97
135
 
98
136
  | Field | Type | Purpose |
99
137
  |-------|------|---------|
100
- | `effort` | `"low" \| "medium" \| "high" \| "xhigh" \| "max"` | Claude effort for `claude -p` (`--effort`) and for the API-key SDK path, which sends it as `output_config.effort`. The SDK path omits it when `QQ_MODEL` names a model without effort support (Haiku 4.5, Sonnet 4.5 or older); a level that a `QQ_MODEL` model does not support (for example `xhigh` on Opus 4.5) is your responsibility. Default `low`. Trimmed and case-insensitive; invalid values fall back to `low` without affecting the rest of the file. Takes effect after the daemon restarts, because the daemon reads config.json once. |
138
+ | `effort` | `"low" \| "medium" \| "high" \| "xhigh" \| "max"` | Claude effort for `claude -p` (`--effort`) and for the API-key SDK path, which sends it as `output_config.effort`. The SDK path omits it when `QQ_MODEL` names a model without effort support (Haiku 4.5, Sonnet 4.5 or older); a level that a `QQ_MODEL` model does not support (for example `xhigh` on Opus 4.5) is your responsibility. Default `low`. Trimmed and case-insensitive; invalid values fall back to `low` without affecting the rest of the file. Takes effect after a [daemon restart](#after-changing-your-key-or-settings), because the daemon reads config.json once. |
101
139
  | `privacy.sensitivePathPatterns` | `string[]` | Extra regex patterns merged onto built-in defaults (`.env`, credentials, keys, etc.). Built-in patterns are never removed. |
102
140
  | `privacy.redactLogKeys` | `string[]` | Extra JSON keys to redact in debug logs (merged with defaults: `lbuffer`, `rbuffer`, `queryText`, `request`). |
103
141
  | `privacy.allowFileRead` | `boolean` | Opt-in gate for future file-content context. Env `QQ_ALLOW_FILE_READ=1` overrides this. No file reads in v1. |
104
142
  | `privacy.useGitignore` | `boolean` | Reserved for future gitignore-based filtering. Ignored today. |
105
143
  | `safety.destructiveCommandPatterns` | `string[]` | Extra warn-only UI patterns merged onto built-in defaults (`rm`, `sudo`, etc.). |
106
144
 
107
- See [docs/SYSTEM_DESIGN.md](docs/SYSTEM_DESIGN.md) for architecture and [docs/EXTENSIONS.md](docs/EXTENSIONS.md) for Phase 7/8 expansion.
145
+ See [docs/SYSTEM_DESIGN.md](docs/SYSTEM_DESIGN.md) for architecture.
108
146
 
109
147
 
package/dist/cli/app.js CHANGED
@@ -60433,7 +60433,7 @@ function CandidateSelect({
60433
60433
  /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(Text, { dimColor: true, children: legend.slice(MISSING_TOOL_MARK.length) })
60434
60434
  ] }),
60435
60435
  /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(ControlsLine, {}),
60436
- process.env.QQ_DEV_ROOT != null && /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(Box_default, { justifyContent: "flex-end", children: /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(Text, { color: "yellow", children: `dev v${"0.6.0"} ${"3d6ffbb"}` }) })
60436
+ process.env.QQ_DEV_ROOT != null && /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(Box_default, { justifyContent: "flex-end", children: /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(Text, { color: "yellow", children: `dev v${"0.6.1"} ${"1a2baf5"}` }) })
60437
60437
  ] });
60438
60438
  }
60439
60439
 
@@ -61186,7 +61186,7 @@ async function main(argv = process.argv.slice(2)) {
61186
61186
  });
61187
61187
  cli.command(
61188
61188
  "init <shell>",
61189
- "Print a source line for shell integration (append to ~/.zshrc with `qq init zsh >> ~/.zshrc`)"
61189
+ "Add shell integration to ~/.zshrc (run `qq init zsh && source ~/.zshrc`)"
61190
61190
  ).action((shell) => {
61191
61191
  initCommand(shell);
61192
61192
  });