ccx-relay 1.5.1 → 1.6.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...
@@ -81,14 +81,14 @@ While the wrapped process is running:
 
 ### 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 +97,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 +109,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

@@ -3,11 +3,10 @@
 import { createInterface } from 'node:readline';
 import { rmSync, existsSync } from 'node:fs';
 import { load, save, configPath } from '../src/config.js';
-import { enhance } from '../src/gemini.js';
+import { enhance, listModels, RateLimitError } from '../src/gemini.js';
 
 const args = process.argv.slice(2);
 
-// Hidden input helper for API key
 async function promptHidden(question) {
   return new Promise(resolve => {
     process.stdout.write(question);
@@ -37,23 +36,19 @@ async function promptHidden(question) {
   });
 }
 
-// Regular prompt helper
 async function prompt(rl, question) {
   return new Promise(resolve => rl.question(question, resolve));
 }
 
-// Mask API key: show first 6 chars + ****...
 function maskKey(key) {
   if (!key) return '(not set)';
   if (key.length <= 6) return key + '****...';
   return key.slice(0, 6) + '****...';
 }
 
-// Show current config
 function showConfig() {
   const config = load();
   const path = configPath();
-
   console.log(`Config: ${path}\n`);
   console.log(`  geminiApiKey:   ${maskKey(config.geminiApiKey)}`);
   console.log(`  geminiModel:    ${config.geminiModel}`);
@@ -61,82 +56,74 @@ function showConfig() {
   console.log(`  timeoutSeconds: ${config.timeoutSeconds}`);
 }
 
-// Reset config
 function resetConfig() {
   const path = configPath();
-
   if (existsSync(path)) {
     rmSync(path);
-    console.log('Config reset. Run `ccx init` to set up again.');
+    console.log('Config reset. Run `ccx-init` to set up again.');
   } else {
     console.log('No config file found — nothing to reset.');
   }
 }
 
-// Interactive wizard
 async function runWizard() {
   console.log('\n  Welcome to ccx setup\n');
 
-  // Step 1: Prompt for API key
   const key = await promptHidden('  API key: ');
-  if (!key) {
-    console.log('No key entered. Aborting.');
-    process.exit(1);
-  }
+  if (!key) { console.log('No key entered. Aborting.'); process.exit(1); }
 
-  // Step 2: Test the key
   process.stdout.write('  Testing key... ');
   try {
     await enhance('hello', { geminiApiKey: key, geminiModel: 'gemini-2.5-flash', timeoutSeconds: 10 });
     console.log('\x1b[32m✓ Valid\x1b[0m');
   } catch (err) {
-    console.log(`\x1b[31m✗ Invalid key\x1b[0m — ${err.message}`);
-    process.exit(1);
+    if (err instanceof RateLimitError) {
+      console.log('\x1b[32m✓ Valid\x1b[0m \x1b[2m(quota exceeded — key authenticated)\x1b[0m');
+    } else {
+      console.log(`\x1b[31m✗ Invalid key\x1b[0m — ${err.message}`);
+      process.exit(1);
+    }
   }
 
-  // Step 3: Model picker
-  const models = [
-    'gemini-2.5-flash',
-    'gemini-1.5-flash',
-    'gemini-2.5-pro'
-  ];
+  // Fetch available models, fall back to hardcoded list
+  let models;
+  process.stdout.write('  Fetching available models... ');
+  try {
+    const all = await listModels(key);
+    models = all.filter(m => m.includes('gemini')).slice(0, 10);
+    if (models.length === 0) throw new Error('empty');
+    console.log(`\x1b[32m✓\x1b[0m ${models.length} found`);
+  } catch (_) {
+    models = ['gemini-2.5-flash', 'gemini-1.5-flash', 'gemini-2.5-pro'];
+    console.log('(using defaults)');
+  }
 
-  const rl = createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
 
   console.log('');
   console.log('  Model:');
-  console.log('  1) gemini-2.5-flash (default)');
-  console.log('  2) gemini-1.5-flash');
-  console.log('  3) gemini-2.5-pro');
+  models.forEach((m, i) => {
+    console.log(`  ${i + 1}) ${m}${i === 0 ? ' (default)' : ''}`);
+  });
 
   const modelChoice = await prompt(rl, '  Choice [1]: ');
-  const modelIndex = modelChoice.trim() === '' || modelChoice.trim() === '1' ? 0 :
-                    modelChoice.trim() === '2' ? 1 :
-                    modelChoice.trim() === '3' ? 2 : 0;
+  const idx = parseInt(modelChoice.trim(), 10);
+  const modelIndex = (!idx || idx < 1 || idx > models.length) ? 0 : idx - 1;
   const model = models[modelIndex];
 
-  // Step 4: Trigger marker
   const markerAnswer = await prompt(rl, '  Trigger marker [;;]: ');
   const marker = markerAnswer.trim() || ';;';
 
-  // Step 5: Timeout seconds
   const timeoutAnswer = await prompt(rl, '  Timeout seconds [8]: ');
   const timeoutSeconds = timeoutAnswer.trim() === '' ? 8 : (parseInt(timeoutAnswer, 10) || 8);
 
   rl.close();
 
-  // Step 6: Save config
   save({ geminiApiKey: key, geminiModel: model, marker, timeoutSeconds });
-
-  // Step 7: Success message
   console.log(`\n  Config saved to ${configPath()}`);
   console.log('  Run `ccx claude` to start.\n');
 }
 
-// Main dispatch
 if (args.length === 0) {
   runWizard();
 } else if (args[0] === '--show') {

package/bin/ccx.js

@@ -6,6 +6,49 @@ import { enhance, RateLimitError, AuthError, ModelError, TimeoutError, NetworkEr
 import { start as spinnerStart, stop as spinnerStop, clear as spinnerClear } from '../src/ui.js';
 import { createInputHandler } from '../src/input.js';
 
+const argv = process.argv.slice(2);
+
+// Shell tab-completion scripts
+if (argv[0] === 'completion') {
+  const shell = argv[1] || 'bash';
+  const scripts = {
+    bash: [
+      '_ccx_completion() {',
+      '    local cur="${COMP_WORDS[COMP_CWORD]}"',
+      '    COMPREPLY=($(compgen -W "claude bash zsh powershell cmd completion" -- "$cur"))',
+      '}',
+      'complete -F _ccx_completion ccx',
+    ].join('\n'),
+    zsh: [
+      '#compdef ccx',
+      '_ccx() {',
+      '    local -a cmds',
+      '    cmds=(claude bash zsh powershell cmd completion)',
+      '    _describe \'command\' cmds',
+      '}',
+      '_ccx',
+    ].join('\n'),
+    powershell: [
+      'Register-ArgumentCompleter -Native -CommandName ccx -ScriptBlock {',
+      '    param($wordToComplete, $commandAst, $cursorPosition)',
+      '    @(\'claude\',\'bash\',\'zsh\',\'powershell\',\'cmd\',\'completion\') | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {',
+      '        [System.Management.Automation.CompletionResult]::new($_, $_, \'ParameterValue\', $_)',
+      '    }',
+      '}',
+    ].join('\n'),
+  };
+  if (!scripts[shell]) {
+    process.stderr.write(`Unknown shell: ${shell}. Use: bash, zsh, powershell\n`);
+    process.exit(1);
+  }
+  process.stdout.write(scripts[shell] + '\n');
+  process.stdout.write('\n# To activate, add to your shell profile:\n');
+  if (shell === 'bash') process.stdout.write('# eval "$(ccx completion bash)"\n');
+  else if (shell === 'zsh') process.stdout.write('# eval "$(ccx completion zsh)"\n');
+  else if (shell === 'powershell') process.stdout.write('# Invoke-Expression (ccx completion powershell)\n');
+  process.exit(0);
+}
+
 let pty;
 try {
   pty = (await import('node-pty')).default;
@@ -21,7 +64,7 @@ try {
 const config = load();
 
 if (!config.geminiApiKey) {
-  process.stderr.write('[ccx] No API key found. Run `ccx init` to set up.\n');
+  process.stderr.write('[ccx] No API key found. Run `ccx-init` to set up.\n');
   process.exit(1);
 }
 
@@ -30,9 +73,8 @@ if (!process.stdin.isTTY || !process.stdout.isTTY) {
   process.exit(1);
 }
 
-const argv      = process.argv.slice(2);
-const targetCmd = argv[0] || 'claude';
-const targetArgs= argv.slice(1);
+const targetCmd  = argv[0] || 'claude';
+const targetArgs = argv.slice(1);
 
 const isWindows = process.platform === 'win32';
 const shellFile = isWindows ? (process.env.COMSPEC || 'cmd.exe') : targetCmd;
@@ -46,7 +88,26 @@ const ptyProcess = pty.spawn(shellFile, shellArgs, {
   env:  process.env,
 });
 
-ptyProcess.onData(data => process.stdout.write(data));
+// Ring buffer of recent PTY output lines for context-aware enhancement
+const CONTEXT_MAX = 20;
+const contextLines = [];
+
+function stripAnsi(s) {
+  return s
+    .replace(/\x1b\[[0-9;]*[A-Za-z]/g, '')
+    .replace(/\x1b\][^\x07]*\x07/g, '')
+    .replace(/\r/g, '');
+}
+
+ptyProcess.onData(data => {
+  process.stdout.write(data);
+  for (const line of stripAnsi(data).split('\n')) {
+    if (line.trim()) {
+      contextLines.push(line.trim());
+      if (contextLines.length > CONTEXT_MAX) contextLines.shift();
+    }
+  }
+});
 
 process.stdout.on('resize', () => {
   ptyProcess.resize(process.stdout.columns, process.stdout.rows);
@@ -58,38 +119,42 @@ process.stdin.resume();
 const handler = createInputHandler({
   marker: config.marker,
 
-  onEnhance: async (line) => {
-    // line may include trailing marker (;;) for the ;; trigger — strip it
+  onEnhance: async (line, cursor) => {
     const toSend = line.endsWith(config.marker) ? line.slice(0, -config.marker.length) : line;
     handler.setBusy(true);
     spinnerStart();
     let improved;
     try {
-      improved = await enhance(toSend, config);
+      const context = contextLines.length > 0 ? contextLines.join('\n') : null;
+      improved = await enhance(toSend, config, context);
     } catch (err) {
       let msg = 'Enhancement failed';
       if (err instanceof RateLimitError) msg = 'Quota exceeded';
-      else if (err instanceof AuthError)  msg = 'Invalid key — run ccx init';
-      else if (err instanceof ModelError) msg = 'Model not found — run ccx init';
+      else if (err instanceof AuthError)    msg = 'Invalid key — run ccx-init';
+      else if (err instanceof ModelError)   msg = 'Model not found — run ccx-init';
       else if (err instanceof TimeoutError) msg = `Timed out after ${config.timeoutSeconds}s — original restored`;
       else if (err instanceof NetworkError) msg = 'No connection — original restored';
       await spinnerStop('error', msg);
-      // Erase full echoed text (including marker if present), restore clean original
+      // Move cursor to end of line then erase, restore original
+      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);
+      handler.setLine(toSend);
       return;
     }
     await spinnerStop('success', 'Enhanced');
-    // Erase full echoed text (including marker), write improved
+    // 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);
+    handler.setLine(improved);
   },
 
-  onSubmit: (_line) => {
-    // Enter already forwarded by input.js passthrough
-  },
+  onSubmit: (_line) => {},
 
   onPassthrough: (chunk) => ptyProcess.write(chunk),
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "ccx-relay",
-  "version": "1.5.1",
+  "version": "1.6.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

@@ -4,79 +4,84 @@ export class ModelError extends Error {}
 export class TimeoutError extends Error {}
 export class NetworkError extends Error {}
 
-const PROMPT_PREFIX =
+const SYSTEM_PROMPT =
   'Rewrite the following text to be grammatically correct and clearer, ' +
   'while preserving its original intent and meaning exactly. ' +
   'This is a single line typed into a terminal prompt, not a chat message - ' +
   'respond with EXACTLY ONE rewritten version as a single plain-text line. ' +
   'Do not offer multiple options or alternatives. Do not add headings, bullet ' +
   'points, markdown formatting, quotes, explanations, or any commentary. ' +
-  'Output must contain nothing but the rewritten line itself.\n\nText:\n';
+  'Output must contain nothing but the rewritten line itself.';
 
-export async function enhance(text, config) {
-  const { geminiApiKey, geminiModel, timeoutSeconds } = config;
+function buildAuthHeaders(apiKey) {
+  // The x-goog-api-key header authenticates both "Auth key" (AQ.-prefixed)
+  // and legacy "Standard key" (AIza-prefixed) formats. Authorization: Bearer
+  // does NOT work here - AQ. keys are not OAuth2 access tokens and return
+  // 401 Unauthorized when sent that way (confirmed against the live API).
+  return { 'x-goog-api-key': apiKey };
+}
+
+export async function listModels(apiKey) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), 10000);
+  try {
+    const response = await fetch(
+      'https://generativelanguage.googleapis.com/v1beta/models',
+      {
+        headers: { 'Content-Type': 'application/json', ...buildAuthHeaders(apiKey) },
+        signal: controller.signal,
+      }
+    );
+    if (!response.ok) throw new AuthError('Could not fetch model list');
+    const data = await response.json();
+    return (data.models || [])
+      .filter(m => m.supportedGenerationMethods?.includes('generateContent'))
+      .map(m => m.name.replace('models/', ''));
+  } catch (err) {
+    if (err instanceof AuthError) throw err;
+    throw new NetworkError('Could not fetch model list');
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
 
+export async function enhance(text, config, context = null) {
+  const { geminiApiKey, geminiModel, timeoutSeconds } = config;
   const url = `https://generativelanguage.googleapis.com/v1beta/models/${geminiModel}:generateContent`;
   const controller = new AbortController();
   let timeoutId;
 
+  const promptText = context
+    ? `${SYSTEM_PROMPT}\n\nRecent terminal context:\n${context}\n\nText:\n${text}`
+    : `${SYSTEM_PROMPT}\n\nText:\n${text}`;
+
   try {
     timeoutId = setTimeout(() => controller.abort(), timeoutSeconds * 1000);
 
-    const authHeaders = geminiApiKey.startsWith('AQ.')
-      ? { 'Authorization': `Bearer ${geminiApiKey}` }
-      : { 'x-goog-api-key': geminiApiKey };
-
     const response = await fetch(url, {
       method: 'POST',
       signal: controller.signal,
-      headers: {
-        'Content-Type': 'application/json',
-        ...authHeaders,
-      },
-      body: JSON.stringify({
-        contents: [{ parts: [{ text: PROMPT_PREFIX + text }] }],
-      }),
+      headers: { 'Content-Type': 'application/json', ...buildAuthHeaders(geminiApiKey) },
+      body: JSON.stringify({ contents: [{ parts: [{ text: promptText }] }] }),
     });
 
-    // Handle bad HTTP status codes
     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 {
-        const truncated = body.substring(0, 200);
-        throw new NetworkError(`API error ${response.status}: ${truncated}`);
-      }
+      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}: ${body.substring(0, 200)}`);
     }
 
-    // Parse response
     const data = await response.json();
     const result = data.candidates[0].content.parts.map(p => p.text || '').join('').trim();
-
-    if (!result) {
-      throw new NetworkError('Gemini returned empty response');
-    }
-
+    if (!result) throw new NetworkError('Gemini returned empty response');
     return result;
   } catch (err) {
-    // Handle fetch errors
-    if (err.name === 'AbortError') {
-      throw new TimeoutError(`Timed out after ${timeoutSeconds}s`);
-    }
-
-    // Re-throw custom errors
+    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;
-    }
-
-    // Wrap other errors as NetworkError
+        err instanceof TimeoutError) throw err;
     throw new NetworkError('No connection');
   } finally {
     clearTimeout(timeoutId);

package/src/input.js

@@ -1,14 +1,3 @@
-/**
- * src/input.js — pure stdin parser with Alt+M and ;; triggers
- * No fetch, no stderr writes, no process.exit
- */
-
-/**
- * Parses ESC [ {digits/semicolons} _ sequences (win32-input-mode)
- * Returns { consumed, vk, sc, uc, kd, cs, rc } or null
- * @param {Buffer} chunk
- * @param {number} i  - index of ESC byte
- */
 function parseWin32InputSeq(chunk, i) {
   if (chunk[i + 1] !== 0x5b) return null;
   let j = i + 2;
@@ -21,16 +10,25 @@ function parseWin32InputSeq(chunk, i) {
   return { consumed: j + 1 - i, vk, sc, uc, kd, cs, rc };
 }
 
-/**
- * @param {{ marker: string, onEnhance: Function, onSubmit: Function, onPassthrough: Function, onCtrlC: Function }} opts
- * @returns {{ processChunk(chunk: Buffer): void, setBusy(b: boolean): void, reset(): void }}
- */
+// Parses standard CSI sequences: ESC [ params final
+function parseCsiSeq(chunk, i) {
+  if (i + 1 >= chunk.length || chunk[i + 1] !== 0x5b) return null;
+  let j = i + 2;
+  while (j < chunk.length && chunk[j] >= 0x20 && chunk[j] <= 0x3f) j++;
+  if (j >= chunk.length || chunk[j] < 0x40 || chunk[j] > 0x7e) return null;
+  const params = chunk.slice(i + 2, j).toString('ascii');
+  const final = String.fromCharCode(chunk[j]);
+  return { consumed: j + 1 - i, params, final };
+}
+
 export function createInputHandler({ marker, onEnhance, onSubmit, onPassthrough, onCtrlC }) {
   let lineBuffer = '';
+  let cursor = 0;
   let busy = false;
 
   function reset() {
     lineBuffer = '';
+    cursor = 0;
     busy = false;
   }
 
@@ -38,40 +36,48 @@ export function createInputHandler({ marker, onEnhance, onSubmit, onPassthrough,
     busy = b;
   }
 
+  // Sync internal buffer after external rewrite (e.g. after enhancement)
+  function setLine(str) {
+    lineBuffer = str;
+    cursor = str.length;
+  }
+
   function processChunk(chunk) {
-    // When busy, forward everything as-is
-    if (busy) {
-      onPassthrough(chunk);
-      return;
-    }
+    if (busy) { onPassthrough(chunk); return; }
 
     let i = 0;
     while (i < chunk.length) {
       const byte = chunk[i];
 
       if (byte === 0x1b) {
-        // Try win32-input-mode sequence first
+        // 1. Win32 input mode sequence
         const seq = parseWin32InputSeq(chunk, i);
         if (seq !== null) {
           if (seq.kd === 1) {
             if (seq.vk === 13) {
-              // Win32 Enter
               if (lineBuffer.endsWith(marker) && lineBuffer.trim().length > marker.length) {
-                onEnhance(lineBuffer);
+                onEnhance(lineBuffer, cursor);
                 return;
               } else {
                 onSubmit(lineBuffer);
                 lineBuffer = '';
+                cursor = 0;
               }
             } else if (seq.vk === 8) {
-              // Win32 Backspace
-              if (lineBuffer.length > 0) lineBuffer = lineBuffer.slice(0, -1);
-            } else if (seq.vk === 77 && (seq.cs & (0x0001 | 0x0002)) && !(seq.cs & (0x0004 | 0x0008))) {
-              // Win32 Alt+M
-              if (lineBuffer.length > 0) {
-                onEnhance(lineBuffer);
-                return;
+              if (cursor > 0) {
+                lineBuffer = lineBuffer.slice(0, cursor - 1) + lineBuffer.slice(cursor);
+                cursor--;
               }
+            } else if (seq.vk === 37) {
+              cursor = Math.max(0, cursor - 1);
+            } else if (seq.vk === 39) {
+              cursor = Math.min(lineBuffer.length, cursor + 1);
+            } else if (seq.vk === 36) {
+              cursor = 0;
+            } 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; }
             }
           }
           onPassthrough(chunk.slice(i, i + seq.consumed));
@@ -79,50 +85,67 @@ export function createInputHandler({ marker, onEnhance, onSubmit, onPassthrough,
           continue;
         }
 
-        // No win32 sequence — check for standard Alt+M (ESC followed by 0x6d)
+        // 2. Alt+M (ESC m)
         if (i + 1 < chunk.length && chunk[i + 1] === 0x6d) {
           if (lineBuffer.length > 0) {
-            onEnhance(lineBuffer);
+            onEnhance(lineBuffer, cursor);
             return;
           } else {
             onPassthrough(chunk.slice(i, i + 2));
             i += 2;
           }
-        } else {
-          // Forward rest untouched
-          onPassthrough(chunk.slice(i));
-          return;
+          continue;
         }
+
+        // 3. Standard CSI sequences (arrows, Home, End, etc.)
+        const csi = parseCsiSeq(chunk, i);
+        if (csi !== null) {
+          if      (csi.final === 'D' && !csi.params) cursor = Math.max(0, cursor - 1);
+          else if (csi.final === 'C' && !csi.params) cursor = Math.min(lineBuffer.length, cursor + 1);
+          else if (csi.final === 'H' && !csi.params) cursor = 0;
+          else if (csi.final === 'F' && !csi.params) cursor = lineBuffer.length;
+          else if (csi.final === '~' && csi.params === '1') cursor = 0;
+          else if (csi.final === '~' && csi.params === '4') cursor = lineBuffer.length;
+          onPassthrough(chunk.slice(i, i + csi.consumed));
+          i += csi.consumed;
+          continue;
+        }
+
+        // 4. Unknown ESC sequence — forward rest of chunk
+        onPassthrough(chunk.slice(i));
+        return;
       } else if (byte === 0x0d) {
-        // Enter
         if (lineBuffer.endsWith(marker) && lineBuffer.trim().length > marker.length) {
-          onEnhance(lineBuffer);
+          onEnhance(lineBuffer, cursor);
           return;
         } else {
           onSubmit(lineBuffer);
           onPassthrough(Buffer.from([byte]));
           lineBuffer = '';
+          cursor = 0;
         }
         i++;
       } else if (byte === 0x03) {
-        // Ctrl+C
         onCtrlC();
         onPassthrough(Buffer.from([byte]));
         lineBuffer = '';
+        cursor = 0;
         i++;
       } else if (byte === 0x7f || byte === 0x08) {
-        // Backspace
-        lineBuffer = lineBuffer.slice(0, -1);
+        if (cursor > 0) {
+          lineBuffer = lineBuffer.slice(0, cursor - 1) + lineBuffer.slice(cursor);
+          cursor--;
+        }
         onPassthrough(Buffer.from([byte]));
         i++;
       } else {
-        // Printable char
-        lineBuffer += String.fromCharCode(byte);
+        lineBuffer = lineBuffer.slice(0, cursor) + String.fromCharCode(byte) + lineBuffer.slice(cursor);
+        cursor++;
         onPassthrough(Buffer.from([byte]));
         i++;
       }
     }
   }
 
-  return { processChunk, setBusy, reset };
+  return { processChunk, setBusy, reset, setLine };
 }

package/src/ui.js

@@ -1,27 +1,17 @@
 const BRAILLE_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
-const FRAME_INTERVAL = 80; // ms
+const FRAME_INTERVAL = 80;
 
 let spinnerInterval = null;
 let currentFrame = 0;
 
-/**
- * Draws the status line on stderr with cursor save/restore
- */
 function drawStatusLine(content) {
-  const ansi = `\x1b[s\r\n\x1b[2K${content}\x1b[u`;
-  process.stderr.write(ansi);
+  const row = process.stdout.rows || 24;
+  process.stderr.write(`\x1b[s\x1b[${row};1H\x1b[2K${content}\x1b[u`);
 }
 
-/**
- * Starts animating the Braille spinner on stderr
- */
 export function start() {
-  // Reset frame counter and stop any existing interval
   currentFrame = 0;
-  if (spinnerInterval) {
-    clearInterval(spinnerInterval);
-  }
-
+  if (spinnerInterval) clearInterval(spinnerInterval);
   spinnerInterval = setInterval(() => {
     const frame = BRAILLE_FRAMES[currentFrame % BRAILLE_FRAMES.length];
     drawStatusLine(`${frame} Enhancing prompt...`);
@@ -29,37 +19,16 @@ export function start() {
   }, FRAME_INTERVAL);
 }
 
-/**
- * Stops the spinner and shows a final status message
- */
 export async function stop(state, message) {
-  // Clear the spinner interval
-  if (spinnerInterval) {
-    clearInterval(spinnerInterval);
-    spinnerInterval = null;
-  }
-
-  // Draw final state based on success/error
+  if (spinnerInterval) { clearInterval(spinnerInterval); spinnerInterval = null; }
   const symbol = state === 'success' ? '✓' : '✗';
   const colorCode = state === 'success' ? '32' : '31';
-  const statusLine = `\x1b[${colorCode}m${symbol} ${message}\x1b[0m`;
-
-  drawStatusLine(statusLine);
-
-  // Wait 400ms
+  drawStatusLine(`\x1b[${colorCode}m${symbol} ${message}\x1b[0m`);
   await new Promise(r => setTimeout(r, 400));
-
-  // Clear the status line
   drawStatusLine('');
 }
 
-/**
- * Immediately clears the status line and stops spinner
- */
 export function clear() {
-  if (spinnerInterval) {
-    clearInterval(spinnerInterval);
-    spinnerInterval = null;
-  }
+  if (spinnerInterval) { clearInterval(spinnerInterval); spinnerInterval = null; }
   drawStatusLine('');
 }

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=;;