ccx-relay 1.7.0 → 1.7.1

package/README.md

@@ -38,7 +38,7 @@ npm install -g ccx-relay
 Run the one-time setup wizard:
 
 ```bash
-ccx init
+ccx-init
 ```
 
 This will prompt for your Gemini API key (get one at https://aistudio.google.com/apikey), validate it, let you pick a model, and save config to your user directory (`%APPDATA%\ccx\config.json` on Windows, `~/.config/ccx/config.json` on macOS/Linux). Config survives npm upgrades.
@@ -46,13 +46,13 @@ This will prompt for your Gemini API key (get one at https://aistudio.google.com
 Other init commands:
 
 ```bash
-ccx init --show    # print current config (key masked)
-ccx init --reset   # wipe config and start over
+ccx-init --show    # print current config (key masked)
+ccx-init --reset   # wipe config and start over
 ```
 
 ### Environment variable override
 
-You can skip `ccx init` and set env vars directly (useful for CI):
+You can skip `ccx-init` and set env vars directly (useful for CI):
 
 ```bash
 export GEMINI_API_KEY=AIza...
@@ -78,17 +78,22 @@ While the wrapped process is running:
 - Review the rewritten line, then press **Enter** to submit it to the child process.
 - A plain line with no trigger submits immediately on Enter, exactly as if `ccx` weren't there.
 - Arrow keys, Ctrl+C, and other control sequences pass through untouched.
+- **Multi-line prompts:** Shift+Enter adds a line break without submitting (same as in a plain Claude Code session).
+  `ccx` tracks the whole multi-line prompt internally, so the marker/Alt+M trigger enhances the entire thing, and a
+  multi-line rewrite gets spliced back in as multiple soft-broken lines rather than being submitted early.
+- Typing ahead while a spinner is running (e.g. mashing Alt+M again) is queued and replayed once the enhancement
+  finishes, instead of leaking into the child mid-rewrite. Ctrl+C still interrupts immediately even while enhancing.
 
 ### Changing the marker
 
-Change `CCX_MARKER` via `ccx init` or env var (default `;;`). No source changes needed.
+Change `CCX_MARKER` via `ccx-init` or env var (default `;;`). No source changes needed.
 
 ## Testing it locally
 
 1. `npm install`
-2. `npm run test` — runs `node --check` against the CLI entry point to catch syntax errors.
+2. `npm test` — runs the unit test suite (`node --test`) covering config loading, the Gemini client, and keystroke handling.
 3. `npm link`
-4. Set up `.env` with a real `GEMINI_API_KEY`.
+4. `ccx-init` — set up your real `GEMINI_API_KEY` (this validates the key and lets you pick a model live).
 5. Sanity-check the relay mechanics with a safe command first, before pointing it at `claude`:
 
    ```bash
@@ -97,9 +102,9 @@ Change `CCX_MARKER` via `ccx init` or env var (default `;;`). No source changes
    ```
 
    You should see a completely normal shell. Type a sentence with a typo, e.g. `pls fix teh bug in server.js;;`,
-   then press **Enter**. You should see `[ccx] enhancing...` flash briefly, then the line rewritten in place
-   (e.g. `Please fix the bug in server.js`) with nothing submitted yet. Press Enter again to run it as a normal
-   shell command.
+   then press **Enter**. You should see a spinner flash briefly (`⠋ Enhancing prompt...`), then `✓ Enhanced`, then
+   the line rewritten in place (e.g. `Please fix the bug in server.js`) with nothing submitted yet. Press Enter
+   again to run it as a normal shell command.
 
 6. Once the mechanics check out, run it against the real target:
 
@@ -109,22 +114,18 @@ Change `CCX_MARKER` via `ccx init` or env var (default `;;`). No source changes
 
 ## Known limitations
 
-- **Works best for single-line prompts typed straight through.** The line buffer is a plain JS string built up as
-  you type; it does not model cursor position.
-- **Heavy mid-line editing via arrow keys is not fully tracked.** Escape sequences (arrow keys, Home/End, etc.) are
-  detected and forwarded to the child untouched so navigation still *works* visually, but `ccx`'s internal buffer
-  does not move its own "cursor" — it only appends on printable input and pops on backspace. If you arrow back into
-  the middle of a line and start editing there, the buffer sent to Gemini (and the backspace count used to erase the
-  line) can drift out of sync with what's actually on screen. Worth testing carefully before relying on it for
-  heavily-edited multi-line pastes.
+- **Cursor position is tracked, including mid-line edits.** Left/Right/Home/End move an internal cursor that stays
+  in sync with inserts, backspace-at-cursor, and both plain-byte and win32-input-mode key encodings — so arrowing
+  back into the middle of a line and editing there is expected to work, including for the enhance trigger.
 - **Byte-wise, not codepoint-wise.** Input is processed one byte at a time; multi-byte UTF-8 characters (accents,
   emoji, non-Latin scripts) may not round-trip through the buffer correctly, though they are still forwarded to the
-  child untouched when you're not invoking the hotkey.
-- **Status line display is best-effort.** `ccx` uses ANSI save/restore-cursor sequences to show and clear the
-  `[ccx] enhancing...` message on its own line. This works in standard ANSI/VT terminals (including the VS Code
-  integrated terminal) but isn't guaranteed on every terminal emulator.
+  child untouched when you're not triggering enhancement.
+- **Status bar display is best-effort.** `ccx` draws the spinner/result to the last row of the terminal via ANSI
+  save/restore-cursor sequences. This works in standard ANSI/VT terminals (including the VS Code integrated
+  terminal) but isn't guaranteed on every terminal emulator, and a terminal resize mid-animation could leave a
+  stray line if the row count changes between draws.
 - **The marker itself is reserved.** If you genuinely need a prompt to end with `;;` literally, either add a
-  trailing space after it or change `CCX_MARKER` to something you don't otherwise type.
+  trailing space after it or change the marker to something you don't otherwise type (via `ccx-init` or `CCX_MARKER`).
 
 ## Windows-specific notes
 

package/bin/ccx-init.js

@@ -72,9 +72,10 @@ async function runWizard() {
   const key = await promptHidden('  API key: ');
   if (!key) { console.log('No key entered. Aborting.'); process.exit(1); }
 
+  const testModel = key.startsWith('gsk_') ? 'llama-3.1-8b-instant' : 'gemini-2.5-flash';
   process.stdout.write('  Testing key... ');
   try {
-    await enhance('hello', { geminiApiKey: key, geminiModel: 'gemini-2.5-flash', timeoutSeconds: 10 });
+    await enhance('hello', { geminiApiKey: key, geminiModel: testModel, timeoutSeconds: 10 });
     console.log('\x1b[32m✓ Valid\x1b[0m');
   } catch (err) {
     if (err instanceof RateLimitError) {

package/bin/ccx.js

@@ -116,10 +116,40 @@ process.stdout.on('resize', () => {
 process.stdin.setRawMode(true);
 process.stdin.resume();
 
+// Windows Console API CONTROL_KEY_STATE flag (see README's win32-input-mode notes;
+// must match SHIFT_PRESSED in src/input.js).
+const SHIFT_PRESSED = 0x0010;
+
+function win32KeyEvent(vk, uc, keyDown, cs) {
+  return `\x1b[${vk};0;${uc};${keyDown ? 1 : 0};${cs};1_`;
+}
+
+// A raw '\r'/'\n' byte written into the pty reads to the wrapped app as a plain
+// Enter keypress, which submits instead of inserting a line break — so a
+// multi-line rewrite (or the original multi-line prompt, on restore-after-error)
+// would get cut off mid-line and the remainder typed as a new, separately
+// submitted line. Encode each embedded newline as a synthetic Shift+Enter
+// win32-input-mode sequence instead, matching how a real Shift+Enter keypress
+// already arrives (see the SHIFT_PRESSED branch in src/input.js).
+function writeTextPreservingLines(text) {
+  const lines = text.split('\n');
+  lines.forEach((line, idx) => {
+    if (line) ptyProcess.write(line);
+    if (idx < lines.length - 1) {
+      if (isWindows) {
+        ptyProcess.write(win32KeyEvent(13, 13, true, SHIFT_PRESSED));
+        ptyProcess.write(win32KeyEvent(13, 13, false, SHIFT_PRESSED));
+      } else {
+        ptyProcess.write('\n');
+      }
+    }
+  });
+}
+
 const handler = createInputHandler({
   marker: config.marker,
 
-  onEnhance: async (line, cursor) => {
+  onEnhance: async (line, cursor, token) => {
     const toSend = line.endsWith(config.marker) ? line.slice(0, -config.marker.length) : line;
     handler.setBusy(true);
     spinnerStart();
@@ -128,6 +158,10 @@ const handler = createInputHandler({
       const context = contextLines.length > 0 ? contextLines.join('\n') : null;
       improved = await enhance(toSend, config, context);
     } catch (err) {
+      // The user may have Ctrl+C'd out (or otherwise moved on) while this was
+      // in flight — reset() bumps the epoch, so an old token here means
+      // whatever we'd write back no longer belongs on the current line.
+      if (!handler.isCurrent(token)) return;
       let msg = 'Enhancement failed';
       if (err instanceof RateLimitError) msg = 'Quota exceeded';
       else if (err instanceof AuthError)    msg = 'Invalid key — run ccx-init';
@@ -139,19 +173,20 @@ const handler = createInputHandler({
       const charsAfterCursor = line.length - cursor;
       if (charsAfterCursor > 0) ptyProcess.write(`\x1b[${charsAfterCursor}C`);
       ptyProcess.write(Buffer.alloc(line.length, 0x7f));
-      ptyProcess.write(toSend);
-      handler.setBusy(false);
+      writeTextPreservingLines(toSend);
       handler.setLine(toSend);
+      handler.setBusy(false);
       return;
     }
+    if (!handler.isCurrent(token)) return;
     await spinnerStop('success', 'Enhanced');
     // Move cursor to end of line then erase, write improved
     const charsAfterCursor = line.length - cursor;
     if (charsAfterCursor > 0) ptyProcess.write(`\x1b[${charsAfterCursor}C`);
     ptyProcess.write(Buffer.alloc(line.length, 0x7f));
-    ptyProcess.write(improved);
-    handler.setBusy(false);
+    writeTextPreservingLines(improved);
     handler.setLine(improved);
+    handler.setBusy(false);
   },
 
   onSubmit: (_line) => {},

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "ccx-relay",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "Transparent PTY wrapper for Claude Code (or any CLI) that lets you refine your prompt with Gemini AI before submitting it, without leaving your terminal session.",
   "main": "bin/ccx.js",
   "bin": {
@@ -11,8 +11,7 @@
   "files": [
     "bin",
     "src",
-    "README.md",
-    ".env.example"
+    "README.md"
   ],
   "scripts": {
     "test": "node --test test/**/*.test.js",

package/src/gemini.js

@@ -13,13 +13,25 @@ const SYSTEM_PROMPT =
   'points, markdown formatting, quotes, explanations, or any commentary. ' +
   'Output must contain nothing but the rewritten line itself.';
 
+function isGroq(apiKey) { return apiKey.startsWith('gsk_'); }
+
 function buildAuthHeaders(apiKey) {
-  return apiKey.startsWith('AQ.')
+  return isGroq(apiKey)
     ? { 'Authorization': `Bearer ${apiKey}` }
     : { 'x-goog-api-key': apiKey };
 }
 
 export async function listModels(apiKey) {
+  if (isGroq(apiKey)) {
+    return [
+      'llama-3.1-8b-instant',
+      'llama-3.3-70b-versatile',
+      'gemma2-9b-it',
+      'llama3-8b-8192',
+      'llama-3.1-70b-versatile',
+    ];
+  }
+
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), 10000);
   try {
@@ -43,7 +55,56 @@ export async function listModels(apiKey) {
   }
 }
 
-export async function enhance(text, config, context = null) {
+async function enhanceGroq(text, config, context) {
+  const { geminiApiKey: apiKey, geminiModel: model, timeoutSeconds } = config;
+  const url = 'https://api.groq.com/openai/v1/chat/completions';
+  const controller = new AbortController();
+  let timeoutId;
+
+  const userContent = context
+    ? `Recent terminal context:\n${context}\n\nText:\n${text}`
+    : text;
+
+  try {
+    timeoutId = setTimeout(() => controller.abort(), timeoutSeconds * 1000);
+
+    const response = await fetch(url, {
+      method: 'POST',
+      signal: controller.signal,
+      headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiKey}` },
+      body: JSON.stringify({
+        model,
+        messages: [
+          { role: 'system', content: SYSTEM_PROMPT },
+          { role: 'user', content: userContent },
+        ],
+        max_tokens: 256,
+      }),
+    });
+
+    if (!response.ok) {
+      if (response.status === 429) throw new RateLimitError('Quota exceeded');
+      else if (response.status === 401 || response.status === 403) throw new AuthError('Invalid key — run ccx-init');
+      else if (response.status === 404) throw new ModelError('Model not found — run ccx-init');
+      else throw new NetworkError(`API error ${response.status}`);
+    }
+
+    const data = await response.json();
+    const result = data.choices[0].message.content.trim();
+    if (!result) throw new NetworkError('Empty response');
+    return result;
+  } catch (err) {
+    if (err.name === 'AbortError') throw new TimeoutError(`Timed out after ${timeoutSeconds}s`);
+    if (err instanceof RateLimitError || err instanceof AuthError ||
+        err instanceof ModelError || err instanceof NetworkError ||
+        err instanceof TimeoutError) throw err;
+    throw new NetworkError('No connection');
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+async function enhanceGemini(text, config, context) {
   const { geminiApiKey, geminiModel, timeoutSeconds } = config;
   const url = `https://generativelanguage.googleapis.com/v1beta/models/${geminiModel}:generateContent`;
   const controller = new AbortController();
@@ -66,8 +127,8 @@ export async function enhance(text, config, context = null) {
     if (!response.ok) {
       const body = await response.text();
       if (response.status === 429) throw new RateLimitError('Quota exceeded');
-      else if (response.status === 401 || response.status === 403) throw new AuthError('Invalid key — run ccx init');
-      else if (response.status === 404) throw new ModelError('Model not found — run ccx init');
+      else if (response.status === 401 || response.status === 403) throw new AuthError('Invalid key — run ccx-init');
+      else if (response.status === 404) throw new ModelError('Model not found — run ccx-init');
       else throw new NetworkError(`API error ${response.status}: ${body.substring(0, 200)}`);
     }
 
@@ -85,3 +146,9 @@ export async function enhance(text, config, context = null) {
     clearTimeout(timeoutId);
   }
 }
+
+export async function enhance(text, config, context = null) {
+  return isGroq(config.geminiApiKey)
+    ? enhanceGroq(text, config, context)
+    : enhanceGemini(text, config, context);
+}

package/src/input.js

@@ -21,19 +21,42 @@ function parseCsiSeq(chunk, i) {
   return { consumed: j + 1 - i, params, final };
 }
 
+// Windows Console API CONTROL_KEY_STATE flag (see README's win32-input-mode notes).
+const SHIFT_PRESSED = 0x0010;
+
 export function createInputHandler({ marker, onEnhance, onSubmit, onPassthrough, onCtrlC }) {
   let lineBuffer = '';
   let cursor = 0;
   let busy = false;
+  let epoch = 0;
+  let pendingWhileBusy = [];
 
   function reset() {
     lineBuffer = '';
     cursor = 0;
     busy = false;
+    pendingWhileBusy = [];
+    epoch++;
+  }
+
+  // Invalidated by reset() (e.g. Ctrl+C) so a still-in-flight enhance that
+  // resolves afterward can tell its result is stale and discard it instead of
+  // writing over whatever the user has moved on to.
+  function isCurrent(token) {
+    return token === epoch;
   }
 
   function setBusy(b) {
+    const wasBusy = busy;
     busy = b;
+    // Replay input that arrived mid-enhancement now that the line has been
+    // updated — see processChunk's busy branch for why it's queued instead
+    // of forwarded live.
+    if (wasBusy && !b && pendingWhileBusy.length > 0) {
+      const queued = pendingWhileBusy;
+      pendingWhileBusy = [];
+      for (const buf of queued) processChunk(buf);
+    }
   }
 
   // Sync internal buffer after external rewrite (e.g. after enhancement)
@@ -43,7 +66,21 @@ export function createInputHandler({ marker, onEnhance, onSubmit, onPassthrough,
   }
 
   function processChunk(chunk) {
-    if (busy) { onPassthrough(chunk); return; }
+    if (busy) {
+      // A lone Ctrl+C still gets through immediately so the wrapped app (and
+      // the user) aren't stuck waiting on a hung enhance call. Everything
+      // else is queued rather than forwarded raw: forwarding live would let
+      // e.g. a mashed Alt+M reach the child unintercepted, silently editing
+      // its buffer in a way ccx's lineBuffer/cursor snapshot never sees —
+      // desyncing the erase-and-replace math once the enhance completes.
+      if (chunk.length === 1 && chunk[0] === 0x03) {
+        onCtrlC();
+        onPassthrough(chunk);
+        return;
+      }
+      pendingWhileBusy.push(Buffer.from(chunk));
+      return;
+    }
 
     let i = 0;
     while (i < chunk.length) {
@@ -55,8 +92,13 @@ export function createInputHandler({ marker, onEnhance, onSubmit, onPassthrough,
         if (seq !== null) {
           if (seq.kd === 1) {
             if (seq.vk === 13) {
-              if (lineBuffer.endsWith(marker) && lineBuffer.trim().length > marker.length) {
-                onEnhance(lineBuffer, cursor);
+              if (seq.cs & SHIFT_PRESSED) {
+                // Shift+Enter: soft line break in the wrapped app's own
+                // multi-line input, not a submit — keep composing.
+                lineBuffer = lineBuffer.slice(0, cursor) + '\n' + lineBuffer.slice(cursor);
+                cursor++;
+              } else if (lineBuffer.endsWith(marker) && lineBuffer.trim().length > marker.length) {
+                onEnhance(lineBuffer, cursor, epoch);
                 return;
               } else {
                 onSubmit(lineBuffer);
@@ -77,7 +119,7 @@ export function createInputHandler({ marker, onEnhance, onSubmit, onPassthrough,
             } else if (seq.vk === 35) {
               cursor = lineBuffer.length;
             } else if (seq.vk === 77 && (seq.cs & (0x0001 | 0x0002)) && !(seq.cs & (0x0004 | 0x0008))) {
-              if (lineBuffer.length > 0) { onEnhance(lineBuffer, cursor); return; }
+              if (lineBuffer.length > 0) { onEnhance(lineBuffer, cursor, epoch); return; }
             }
           }
           onPassthrough(chunk.slice(i, i + seq.consumed));
@@ -88,7 +130,7 @@ export function createInputHandler({ marker, onEnhance, onSubmit, onPassthrough,
         // 2. Alt+M (ESC m)
         if (i + 1 < chunk.length && chunk[i + 1] === 0x6d) {
           if (lineBuffer.length > 0) {
-            onEnhance(lineBuffer, cursor);
+            onEnhance(lineBuffer, cursor, epoch);
             return;
           } else {
             onPassthrough(chunk.slice(i, i + 2));
@@ -116,7 +158,7 @@ export function createInputHandler({ marker, onEnhance, onSubmit, onPassthrough,
         return;
       } else if (byte === 0x0d) {
         if (lineBuffer.endsWith(marker) && lineBuffer.trim().length > marker.length) {
-          onEnhance(lineBuffer, cursor);
+          onEnhance(lineBuffer, cursor, epoch);
           return;
         } else {
           onSubmit(lineBuffer);
@@ -147,5 +189,5 @@ export function createInputHandler({ marker, onEnhance, onSubmit, onPassthrough,
     }
   }
 
-  return { processChunk, setBusy, reset, setLine };
+  return { processChunk, setBusy, reset, setLine, isCurrent };
 }

package/.env.example

@@ -1,12 +0,0 @@
-# Google Gemini API key (required).
-# Get one at https://aistudio.google.com/apikey
-GEMINI_API_KEY=
-
-# Gemini model to use for prompt rewriting (optional).
-# Default: gemini-3.5-flash
-GEMINI_MODEL=gemini-3.5-flash
-
-# Trailing marker that triggers "enhance current line" when you press Enter
-# (optional). Type your prompt, append this marker, then press Enter once to
-# enhance (not submit) - press Enter again to actually submit. Default: ;;
-CCX_MARKER=;;