@superdots/airtype 0.4.0

package/src/audio.ts

@@ -0,0 +1,110 @@
+import { spawn } from "child_process";
+
+export interface Recorder {
+  stop: () => Promise<Buffer>;
+  onVolume: (cb: (level: number) => void) => void;
+}
+
+/**
+ * Record audio to stdout as raw PCM, calculate volume in JS,
+ * accumulate buffer for WAV conversion on stop.
+ * Single rec process — no device conflict.
+ */
+export function startRecording(micDevice = "default"): Recorder {
+  // Switch macOS input device if specified
+  if (micDevice !== "default") {
+    try {
+      const { execSync } = require("child_process");
+      execSync(`SwitchAudioSource -t input -s "${micDevice}"`, { stdio: "ignore" });
+    } catch {}
+  }
+
+  // Output raw PCM to stdout, 16kHz mono 16-bit
+  const proc = spawn("rec", [
+    "-q", "-r", "16000", "-c", "1", "-b", "16",
+    "-t", "raw", "-",  // raw PCM to stdout
+  ], { stdio: ["pipe", "pipe", "pipe"] });
+
+  const chunks: Buffer[] = [];
+  let volumeCb: ((level: number) => void) | null = null;
+
+  proc.stdout?.on("data", (chunk: Buffer) => {
+    chunks.push(chunk);
+
+    if (!volumeCb) return;
+    // Calculate RMS from raw 16-bit PCM
+    let sum = 0;
+    const samples = Math.floor(chunk.length / 2);
+    for (let i = 0; i < chunk.length - 1; i += 2) {
+      const sample = chunk.readInt16LE(i) / 32768;
+      sum += sample * sample;
+    }
+    const rms = Math.sqrt(sum / Math.max(samples, 1));
+    // Voice RMS: ~0.005-0.3, noise floor: ~0.0001
+    // Scale so normal speech fills ~60-80% of the bar
+    const level = Math.min(1, rms * 20);
+    volumeCb(level);
+  });
+
+  return {
+    onVolume: (cb) => { volumeCb = cb; },
+    stop: () =>
+      new Promise((resolve, reject) => {
+        proc.on("close", () => {
+          try {
+            const pcm = Buffer.concat(chunks);
+            const wav = pcmToWav(pcm, 16000, 1, 16);
+            resolve(wav);
+          } catch (e) {
+            reject(e);
+          }
+        });
+        proc.kill("SIGTERM");
+      }),
+  };
+}
+
+/** Convert raw PCM to WAV buffer */
+function pcmToWav(pcm: Buffer, sampleRate: number, channels: number, bitsPerSample: number): Buffer {
+  const byteRate = sampleRate * channels * (bitsPerSample / 8);
+  const blockAlign = channels * (bitsPerSample / 8);
+  const header = Buffer.alloc(44);
+
+  header.write("RIFF", 0);
+  header.writeUInt32LE(36 + pcm.length, 4);
+  header.write("WAVE", 8);
+  header.write("fmt ", 12);
+  header.writeUInt32LE(16, 16);           // chunk size
+  header.writeUInt16LE(1, 20);            // PCM format
+  header.writeUInt16LE(channels, 22);
+  header.writeUInt32LE(sampleRate, 24);
+  header.writeUInt32LE(byteRate, 28);
+  header.writeUInt16LE(blockAlign, 32);
+  header.writeUInt16LE(bitsPerSample, 34);
+  header.write("data", 36);
+  header.writeUInt32LE(pcm.length, 40);
+
+  return Buffer.concat([header, pcm]);
+}
+
+/** Record for a fixed duration (for block tests) */
+export async function recordDuration(seconds: number, micDevice = "default"): Promise<Buffer> {
+  const tmpFile = `/tmp/airtype-${Date.now()}.wav`;
+
+  const proc = spawn("rec", ["-q", "-r", "16000", "-c", "1", "-b", "16", tmpFile, "trim", "0", String(seconds)], {
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+
+  return new Promise((resolve, reject) => {
+    proc.on("close", async () => {
+      try {
+        const file = Bun.file(tmpFile);
+        const buffer = Buffer.from(await file.arrayBuffer());
+        resolve(buffer);
+      } catch (e) {
+        reject(e);
+      }
+    });
+    proc.on("error", reject);
+  });
+}

package/src/config.ts

@@ -0,0 +1,91 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+/** Base directory for all airtype data: ~/.airtype/ */
+export const AIRTYPE_HOME = join(homedir(), ".airtype");
+export const airpath = (...parts: string[]) => join(AIRTYPE_HOME, ...parts);
+
+// Ensure base dir exists on import
+mkdirSync(AIRTYPE_HOME, { recursive: true });
+mkdirSync(airpath("logs"), { recursive: true });
+mkdirSync(airpath("recordings"), { recursive: true });
+
+const CONFIG_PATH = airpath("config.json");
+const ENV_PATH = airpath(".env");
+
+export interface AirtypeConfig {
+  micDevice: string;
+  language: string;
+  shortcutDisplay: string;
+  shortcutKeys: string[];
+  autoEnter: boolean;
+  wordCount: number;
+  testPassed: boolean;
+  onboardingDone: boolean;
+}
+
+const defaults: AirtypeConfig = {
+  micDevice: "default",
+  language: "auto",
+  shortcutDisplay: "",
+  shortcutKeys: [],
+  autoEnter: true,
+  wordCount: 0,
+  testPassed: false,
+  onboardingDone: false,
+};
+
+export function loadConfig(): AirtypeConfig {
+  if (existsSync(CONFIG_PATH)) {
+    try {
+      return { ...defaults, ...JSON.parse(readFileSync(CONFIG_PATH, "utf-8")) };
+    } catch {
+      return { ...defaults };
+    }
+  }
+  return { ...defaults };
+}
+
+export function saveConfig(config: AirtypeConfig) {
+  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
+}
+
+export function loadEnvKey(key: string): string {
+  if (existsSync(ENV_PATH)) {
+    const lines = readFileSync(ENV_PATH, "utf-8").split("\n");
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith("#") || !trimmed) continue;
+      const eq = trimmed.indexOf("=");
+      if (eq > 0 && trimmed.slice(0, eq).trim() === key) {
+        return trimmed.slice(eq + 1).trim();
+      }
+    }
+  }
+  return process.env[key] || "";
+}
+
+
+export function isReady(config: AirtypeConfig): boolean {
+  return !!(
+    config.onboardingDone &&
+    config.shortcutKeys.length > 0 &&
+    config.micDevice && config.micDevice !== "default" &&
+    config.testPassed
+  );
+}
+
+const FREE_WORD_LIMIT = 10000;
+
+/** Add words and save. Returns true if over free limit. */
+export function addWords(config: AirtypeConfig, text: string): boolean {
+  const words = text.trim().split(/\s+/).length;
+  config.wordCount = (config.wordCount || 0) + words;
+  saveConfig(config);
+  return config.wordCount > FREE_WORD_LIMIT;
+}
+
+export function isOverLimit(config: AirtypeConfig): boolean {
+  return (config.wordCount || 0) > FREE_WORD_LIMIT;
+}

package/src/keys.ts

@@ -0,0 +1,54 @@
+import type { IGlobalKeyDownMap } from "node-global-key-listener";
+
+/**
+ * Build a shortcut display string from the current isDown map + pressed key name.
+ * Uses the isDown map provided by node-global-key-listener (second callback arg).
+ * This is the authoritative modifier state — no manual tracking needed.
+ */
+export function buildCombo(keyName: string, isDown: IGlobalKeyDownMap): string {
+  const parts: string[] = [];
+
+  if (isDown["LEFT META"] || isDown["RIGHT META"]) parts.push("Cmd");
+  if (isDown["LEFT CTRL"] || isDown["RIGHT CTRL"]) parts.push("Ctrl");
+  if (isDown["LEFT ALT"] || isDown["RIGHT ALT"]) parts.push("Alt");
+  if (isDown["LEFT SHIFT"] || isDown["RIGHT SHIFT"]) parts.push("Shift");
+
+  // Don't add modifier names as the key itself
+  if (!isModifier(keyName)) {
+    parts.push(keyName);
+  }
+
+  const result = parts.join("+");
+
+  // Raw log every key event for debugging
+  const fs = require("fs");
+  const { airpath } = require("./config.js");
+  const ts = new Date().toISOString();
+  const logLine = JSON.stringify({ ts, keyName, combo: result, isDown: Object.fromEntries(Object.entries(isDown).filter(([_, v]) => v)) }) + "\n";
+  try { fs.appendFileSync(airpath("logs", "keystrokes.jsonl"), logLine); } catch {}
+
+  return result;
+}
+
+/** Debounce shortcut — returns true if this is a duplicate within 200ms */
+let lastCombo = "";
+let lastTime = 0;
+
+export function isDuplicate(combo: string): boolean {
+  const now = Date.now();
+  if (combo === lastCombo && now - lastTime < 200) {
+    return true;
+  }
+  lastCombo = combo;
+  lastTime = now;
+  return false;
+}
+
+export function isModifier(name: string): boolean {
+  return [
+    "LEFT META", "RIGHT META",
+    "LEFT CTRL", "RIGHT CTRL",
+    "LEFT ALT", "RIGHT ALT",
+    "LEFT SHIFT", "RIGHT SHIFT",
+  ].includes(name);
+}

package/src/llm.ts

@@ -0,0 +1,63 @@
+const PROXY_URL = "https://airtype-xi.vercel.app/api/llm";
+
+const SYSTEM_PROMPT = `You are a voice-to-text polish assistant. Your job is to clean up raw speech transcription into well-written, professionally formatted text.
+
+Rules:
+1. ALWAYS output in English, even if the input is in Korean or another language — translate naturally
+2. Add proper punctuation (periods, commas, question marks)
+3. Remove filler words (um, uh, 음, 어, 그)
+4. Fix grammar while preserving the original meaning exactly
+5. Preserve technical terms, proper nouns, and numbers exactly
+6. Output ONLY the polished text, no explanations
+7. Do not add or remove any meaning
+8. Fix common STT mishearings using context (e.g. technical terms the speaker likely intended)
+
+Smart Formatting — automatically detect and apply the best structure:
+- Sequential items (first/second/third, one/two/three, step 1/2/3) → numbered list (1. 2. 3.)
+- Parallel items (also, and, another thing) → bullet list (- item)
+- Email-like speech (dear X, regards, sincerely) → email format with line breaks
+- Long continuous speech → split into paragraphs at natural topic boundaries
+- Time references: "2 30 pm" → 2:30 PM, "10 am" → 10:00 AM
+- Percentages: "40 percent" → 40%
+- Voice punctuation commands: "new line" → \\n, "new paragraph" → \\n\\n, "period" → ., "comma" → ,, "question mark" → ?
+
+Hesitation & Repetition Clearing — remove false starts and self-corrections, keep only the final intent:
+- "I think... no wait... I believe X" → "I believe X"
+- "um I know that... I knew that is good" → "I knew that is good"
+- "so the thing is... what I mean is... we need X" → "We need X"
+- Stuttered words: "the the the problem" → "The problem"
+- Abandoned sentences followed by restart: keep only the restart`;
+
+export interface LlmResult {
+  text: string;
+  durationMs: number;
+}
+
+export async function polish(rawText: string, model = "google/gemini-2.5-flash"): Promise<LlmResult> {
+  const start = Date.now();
+
+  const resp = await fetch(PROXY_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      model,
+      messages: [
+        { role: "system", content: SYSTEM_PROMPT },
+        { role: "user", content: `<transcription>${rawText}</transcription>` },
+      ],
+      max_tokens: 4096,
+      temperature: 0.3,
+    }),
+  });
+
+  const body = await resp.text();
+  const durationMs = Date.now() - start;
+
+  if (!resp.ok) {
+    throw new Error(`LLM failed (${resp.status}): ${body}`);
+  }
+
+  const parsed = JSON.parse(body);
+  const text = parsed.choices?.[0]?.message?.content || "";
+  return { text, durationMs };
+}

package/src/onboarding.ts

@@ -0,0 +1,273 @@
+import { execSync } from "child_process";
+import { GlobalKeyboardListener } from "node-global-key-listener";
+import { loadEnvKey, saveConfig, type AirtypeConfig } from "./config.js";
+import { recordDuration } from "./audio.js";
+import { transcribe } from "./stt.js";
+import { polish } from "./llm.js";
+import inquirer from "inquirer";
+
+const CYAN = "\x1b[36m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const RED = "\x1b[31m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const RESET = "\x1b[0m";
+
+export async function runOnboarding(config: AirtypeConfig) {
+  console.log(`
+${CYAN}    ╭─────────────────────────────────────╮
+    │                                     │
+    │  ░█▀█░▀█▀░█▀▄░▀█▀░█░█░█▀█░█▀▀     │
+    │  ░█▀█░░█░░█▀▄░░█░░░█░░█▀▀░█▀▀     │
+    │  ░▀░▀░▀▀▀░▀░▀░░▀░░░▀░░▀░░░▀▀▀     │
+    │                                     │
+    │     hands-free transcription         │
+    │             v0.2.0                   │
+    ╰─────────────────────────────────────╯${RESET}
+
+  Welcome to Airtype. Let's set things up.
+`);
+
+  // Step 1: Mic Permission
+  console.log(`  ${CYAN}${BOLD}[1/7] Microphone Permission${RESET}`);
+  try {
+    execSync("rec -q -r 16000 -c 1 /tmp/airtype-test.wav trim 0 0.1", { stdio: "ignore" });
+    console.log(`  ${GREEN}${BOLD}✓${RESET} Microphone access granted\n`);
+  } catch {
+    console.log(`  ${RED}${BOLD}✗${RESET} Microphone access denied. Grant permission in System Settings.\n`);
+  }
+
+  // Step 2: Accessibility
+  console.log(`  ${CYAN}${BOLD}[2/7] Accessibility Permission${RESET}`);
+  console.log(`  ${DIM}Needed to paste text into other apps.${RESET}`);
+  console.log(`  ${DIM}Opening System Settings...${RESET}\n`);
+  execSync("open 'x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility'");
+  console.log(`  ${DIM}Find your terminal app and toggle it ON.${RESET}\n`);
+  await prompt("  Press Enter when done... ");
+  console.log(`  ${GREEN}${BOLD}✓${RESET} Accessibility configured\n`);
+
+  // Step 3: Mic Selection
+  console.log(`  ${CYAN}${BOLD}[3/7] Microphone Selection${RESET}\n`);
+  const mics = getMicrophones();
+  const { mic } = await inquirer.prompt([{
+    type: "list",
+    name: "mic",
+    message: "Select microphone:",
+    choices: mics,
+  }]);
+  config.micDevice = mic;
+  console.log(`  ${GREEN}${BOLD}✓${RESET} ${mic}\n`);
+
+  // Step 4: Shortcut
+  console.log(`  ${CYAN}${BOLD}[4/7] Shortcut Key Binding${RESET}`);
+  console.log(`  ${DIM}Press your desired shortcut combo from anywhere.${RESET}`);
+  console.log(`  ${DIM}Must include a modifier: Ctrl/Alt/Shift/Cmd + key${RESET}\n`);
+  console.log(`  ${BOLD}Waiting for keypress...${RESET}`);
+
+  const shortcut = await captureShortcut();
+  config.shortcutDisplay = shortcut.display;
+  config.shortcutKeys = shortcut.keys;
+  console.log(`  ${GREEN}${BOLD}✓${RESET} Shortcut: ${shortcut.display}\n`);
+
+  // Step 5: API Keys
+  console.log(`  ${CYAN}${BOLD}[5/7] API Keys${RESET}`);
+  const envGroq = loadEnvKey("GROQ_API_KEY");
+  const envOr = loadEnvKey("OPENROUTER_API_KEY");
+  if (envGroq && envOr) {
+    config.groqApiKey = envGroq;
+    config.openrouterApiKey = envOr;
+    console.log(`  ${DIM}Found in .env${RESET}`);
+    console.log(`  ${GREEN}${BOLD}✓${RESET} API keys loaded\n`);
+  } else {
+    if (!config.groqApiKey) {
+      const { key } = await inquirer.prompt([{ type: "input", name: "key", message: "Groq API key (console.groq.com):" }]);
+      config.groqApiKey = key;
+    }
+    if (!config.openrouterApiKey) {
+      const { key } = await inquirer.prompt([{ type: "input", name: "key", message: "OpenRouter API key (openrouter.ai):" }]);
+      config.openrouterApiKey = key;
+    }
+    console.log(`  ${GREEN}${BOLD}✓${RESET} API keys saved\n`);
+  }
+
+  // Step 6: Language
+  console.log(`  ${CYAN}${BOLD}[6/7] Language${RESET}\n`);
+  const { lang } = await inquirer.prompt([{
+    type: "list",
+    name: "lang",
+    message: "Transcription language:",
+    choices: [
+      { name: "Auto-detect (recommended)", value: "auto" },
+      { name: "Korean (한국어)", value: "ko" },
+      { name: "English", value: "en" },
+      { name: "Japanese (日本語)", value: "ja" },
+    ],
+  }]);
+  config.language = lang;
+
+  // Step 7: Guided Test
+  console.log(`\n  ${CYAN}${BOLD}[7/7] Guided Test${RESET}`);
+  console.log(`  ${DIM}Try 3 recordings with your shortcut key.${RESET}`);
+  console.log(`  ${DIM}Read each sentence aloud to see the result.${RESET}\n`);
+
+  const tests = [
+    { label: "Hesitation Clearing", sentence: "Um so I think we should... no wait... we need to fix the login bug" },
+    { label: "Auto Numbered List", sentence: "First update the API docs second fix the timeout bug third deploy to staging" },
+    { label: "Email Format", sentence: "Dear Michael new line I wanted to follow up on our meeting period Best regards Chris" },
+  ];
+
+  for (let i = 0; i < tests.length; i++) {
+    const { label, sentence } = tests[i]!;
+
+    console.log(`  ${CYAN}╭─ [${i + 1}/3] ${label} ${"─".repeat(Math.max(0, 42 - label.length))}╮${RESET}`);
+    console.log(`  ${CYAN}│${RESET}                                                  ${CYAN}│${RESET}`);
+    console.log(`  ${CYAN}│${RESET}  ${BOLD}${`Say: "${sentence}"`}${RESET}`);
+    console.log(`  ${CYAN}│${RESET}                                                  ${CYAN}│${RESET}`);
+    console.log(`  ${CYAN}│${RESET}  Press ${BOLD}${config.shortcutDisplay}${RESET} to start, press again to stop.  ${CYAN}│${RESET}`);
+    console.log(`  ${CYAN}│${RESET}                                                  ${CYAN}│${RESET}`);
+    console.log(`  ${CYAN}╰${"─".repeat(50)}╯${RESET}\n`);
+
+    // Wait for shortcut press → record → shortcut press → stop → process
+    const wavBuffer = await recordWithShortcut(config);
+
+    console.log(`  ${YELLOW}Processing...${RESET}`);
+    try {
+      const sttResult = await transcribe(config.groqApiKey, wavBuffer, config.language);
+      const llmResult = await polish(config.openrouterApiKey, sttResult.text);
+
+      console.log(`  ${DIM}You said:${RESET}  ${sttResult.text.trim()}`);
+      console.log(`  ${GREEN}${BOLD}Result:${RESET}    ${BOLD}${llmResult.text}${RESET}`);
+      console.log(`  ${DIM}${sttResult.durationMs + llmResult.durationMs}ms${RESET}\n`);
+    } catch (e: any) {
+      console.log(`  ${RED}Error: ${e.message}${RESET}\n`);
+    }
+  }
+
+  console.log(`  ${GREEN}${BOLD}✓${RESET} All 3 tests done! You're ready to use Airtype.\n`);
+
+  config.onboardingDone = true;
+  saveConfig(config);
+}
+
+// ─── Helpers ─────────────────────────────────────
+
+function getMicrophones(): string[] {
+  try {
+    const output = execSync("system_profiler SPAudioDataType 2>/dev/null", { encoding: "utf-8" });
+    const names: string[] = [];
+    for (const line of output.split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed.endsWith(":") && !trimmed.startsWith("Audio") && !trimmed.startsWith("Devices") && !trimmed.startsWith("Input") && !trimmed.startsWith("Output")) {
+        const name = trimmed.replace(/:$/, "").trim();
+        if (name && !names.includes(name)) names.push(name);
+      }
+    }
+    if (names.length === 0) names.push("default");
+    return names;
+  } catch {
+    return ["default"];
+  }
+}
+
+function captureShortcut(): Promise<{ display: string; keys: string[] }> {
+  return new Promise((resolve) => {
+    const listener = new GlobalKeyboardListener();
+    const heldMods = new Set<string>();
+
+    listener.addListener((e) => {
+      const name = e.name || "";
+
+      // Track modifier presses
+      if (["LEFT META", "RIGHT META", "LEFT CTRL", "RIGHT CTRL", "LEFT ALT", "RIGHT ALT", "LEFT SHIFT", "RIGHT SHIFT"].includes(name)) {
+        if (e.state === "DOWN") {
+          if (name.includes("META")) heldMods.add("Cmd");
+          if (name.includes("CTRL")) heldMods.add("Ctrl");
+          if (name.includes("ALT")) heldMods.add("Alt");
+          if (name.includes("SHIFT")) heldMods.add("Shift");
+        }
+        return;
+      }
+
+      // Non-modifier key pressed with at least one modifier held
+      if (e.state === "DOWN" && heldMods.size > 0) {
+        const keys = [...heldMods, name];
+        const display = keys.join("+");
+        listener.kill();
+        resolve({ display, keys });
+      }
+    });
+  });
+}
+
+function recordWithShortcut(config: AirtypeConfig): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const listener = new GlobalKeyboardListener();
+    let recording = false;
+    let recProc: any = null;
+    const heldMods = new Set<string>();
+    const target = config.shortcutDisplay;
+
+    listener.addListener((e) => {
+      const name = e.name || "";
+
+      // Track modifiers
+      if (["LEFT META", "RIGHT META", "LEFT CTRL", "RIGHT CTRL", "LEFT ALT", "RIGHT ALT", "LEFT SHIFT", "RIGHT SHIFT"].includes(name)) {
+        if (e.state === "DOWN") {
+          if (name.includes("META")) heldMods.add("Cmd");
+          if (name.includes("CTRL")) heldMods.add("Ctrl");
+          if (name.includes("ALT")) heldMods.add("Alt");
+          if (name.includes("SHIFT")) heldMods.add("Shift");
+        } else {
+          if (name.includes("META")) heldMods.delete("Cmd");
+          if (name.includes("CTRL")) heldMods.delete("Ctrl");
+          if (name.includes("ALT")) heldMods.delete("Alt");
+          if (name.includes("SHIFT")) heldMods.delete("Shift");
+        }
+        return;
+      }
+
+      if (e.state !== "DOWN") return;
+
+      const pressed = [...heldMods, name].join("+");
+      if (pressed !== target) return;
+
+      if (!recording) {
+        // Start
+        recording = true;
+        playSound("Glass");
+        console.log(`  ${RED}${BOLD}🎙 Recording...${RESET}`);
+
+        const { spawn } = require("child_process");
+        const tmpFile = `/tmp/airtype-onboard-${Date.now()}.wav`;
+        recProc = { proc: spawn("rec", ["-q", "-r", "16000", "-c", "1", "-b", "16", tmpFile], { stdio: "pipe" }), file: tmpFile };
+      } else {
+        // Stop
+        playSound("Pop");
+        listener.kill();
+
+        const { proc, file } = recProc;
+        proc.on("close", async () => {
+          try {
+            const buf = Buffer.from(await Bun.file(file).arrayBuffer());
+            resolve(buf);
+          } catch (err) {
+            reject(err);
+          }
+        });
+        proc.kill("SIGTERM");
+      }
+    });
+  });
+}
+
+function playSound(name: string) {
+  try { execSync(`afplay /System/Library/Sounds/${name}.aiff &`, { stdio: "ignore" }); } catch {}
+}
+
+function prompt(msg: string): Promise<void> {
+  return new Promise((resolve) => {
+    process.stdout.write(msg);
+    process.stdin.once("data", () => resolve());
+  });
+}

package/src/paste.ts

@@ -0,0 +1,85 @@
+import { spawn, execSync } from "child_process";
+import { appendFileSync } from "fs";
+import { airpath } from "./config.js";
+
+/** Copy text to clipboard and Cmd+V via osascript. Logs everything for debugging. */
+export async function pasteText(text: string, autoEnter = true): Promise<number> {
+  const start = Date.now();
+  const logPath = airpath("logs", "paste.jsonl");
+
+  const log = (data: Record<string, any>) => {
+    appendFileSync(logPath, JSON.stringify({ ts: new Date().toISOString(), ...data }) + "\n");
+  };
+
+  // What app is focused right now?
+  let focusedApp = "unknown";
+  try {
+    focusedApp = execSync(
+      `osascript -e 'tell application "System Events" to get name of first application process whose frontmost is true'`,
+      { timeout: 2000, encoding: "utf-8" }
+    ).trim();
+  } catch {}
+
+  log({ step: "start", focusedApp, textLen: text.length });
+
+  // Set clipboard via pbcopy
+  const pbcopy = spawn("pbcopy", [], { stdio: ["pipe", "pipe", "pipe"] });
+  pbcopy.stdin.write(text);
+  pbcopy.stdin.end();
+  await new Promise<void>((resolve) => pbcopy.on("close", () => resolve()));
+
+  // Verify clipboard was set
+  let clipboardOk = false;
+  try {
+    const clip = execSync("pbpaste", { timeout: 1000, encoding: "utf-8" });
+    clipboardOk = clip.length > 0 && clip.slice(0, 50) === text.slice(0, 50);
+  } catch {}
+
+  log({ step: "clipboard", ok: clipboardOk });
+
+  await new Promise((r) => setTimeout(r, 80));
+
+  // Cmd+V via osascript
+  let pasteOk = false;
+  let pasteError = "";
+  try {
+    const result = execSync(
+      `osascript -e 'tell application "System Events" to keystroke "v" using command down' 2>&1`,
+      { timeout: 3000, encoding: "utf-8" }
+    );
+    pasteOk = true;
+    log({ step: "paste", ok: true, focusedApp });
+  } catch (e: any) {
+    pasteError = e.message?.slice(0, 200) || "unknown";
+    log({ step: "paste", ok: false, error: pasteError, focusedApp });
+
+    // Retry once
+    await new Promise((r) => setTimeout(r, 200));
+    try {
+      execSync(`osascript -e 'tell application "System Events" to keystroke "v" using command down'`, { timeout: 3000 });
+      pasteOk = true;
+      log({ step: "paste-retry", ok: true });
+    } catch (e2: any) {
+      log({ step: "paste-retry", ok: false, error: e2.message?.slice(0, 200) });
+    }
+  }
+
+  if (!pasteOk) {
+    console.error(`  ⚠ Paste failed (app: ${focusedApp}) — text is in clipboard, Cmd+V to paste`);
+  }
+
+  // Auto-enter after paste
+  if (pasteOk && autoEnter) {
+    await new Promise((r) => setTimeout(r, 100));
+    try {
+      execSync(`osascript -e 'tell application "System Events" to keystroke return'`, { timeout: 2000 });
+      log({ step: "auto-enter", ok: true });
+    } catch (e: any) {
+      log({ step: "auto-enter", ok: false, error: e.message?.slice(0, 100) });
+    }
+  }
+
+  const elapsed = Date.now() - start;
+  log({ step: "done", elapsed, pasteOk, autoEnter });
+  return elapsed;
+}